[Console] Fixed and completed PHPDoc

src/Symfony/Component/Console/Application.php

@@ -85,7 +85,7 @@ public function __construct($name = 'UNKNOWN', $version = 'UNKNOWN')
             new InputOption('--help',           '-h', InputOption::VALUE_NONE, 'Display this help message.'),
             new InputOption('--quiet',          '-q', InputOption::VALUE_NONE, 'Do not output any message.'),
             new InputOption('--verbose',        '-v', InputOption::VALUE_NONE, 'Increase verbosity of messages.'),
-            new InputOption('--version',        '-V', InputOption::VALUE_NONE, 'Display this program version.'),
+            new InputOption('--version',        '-V', InputOption::VALUE_NONE, 'Display this application version.'),
             new InputOption('--ansi',           '',   InputOption::VALUE_NONE, 'Force ANSI output.'),
             new InputOption('--no-ansi',        '',   InputOption::VALUE_NONE, 'Disable ANSI output.'),
             new InputOption('--no-interaction', '-n', InputOption::VALUE_NONE, 'Do not ask any interactive question.'),
@@ -836,6 +836,14 @@ private function getAbbreviationSuggestions($abbrevs)
         return sprintf('%s, %s%s', $abbrevs[0], $abbrevs[1], count($abbrevs) > 2 ? sprintf(' and %d more', count($abbrevs) - 2) : '');
     }
 
+    /**
+     * Returns the namespace part of the command name.
+     *
+     * @param string $name  The full name of the command
+     * @param string $limit The maximum number of parts of the namespace
+     *
+     * @return string The namespace of the command
+     */
     private function extractNamespace($name, $limit = null)
     {
         $parts = explode(':', $name);

src/Symfony/Component/Console/Formatter/OutputFormatter.php

@@ -32,7 +32,7 @@ class OutputFormatter implements OutputFormatterInterface
      * Initializes console output formatter.
      *
      * @param   Boolean $decorated  Whether this formatter should actually decorate strings
-     * @param   array   $styles     Array of "name => FormatterStyle" instance
+     * @param   array   $styles     Array of "name => FormatterStyle" instances
      *
      * @api
      */
@@ -53,7 +53,7 @@ public function __construct($decorated = null, array $styles = array())
     /**
      * Sets the decorated flag.
      *
-     * @param Boolean $decorated Whether to decorated the messages or not
+     * @param Boolean $decorated Whether to decorate the messages or not
      *
      * @api
      */
@@ -108,6 +108,8 @@ public function hasStyle($name)
      *
      * @return  OutputFormatterStyleInterface
      *
+     * @throws  \InvalidArgumentException When style isn't defined
+     *
      * @api
      */
     public function getStyle($name)

src/Symfony/Component/Console/Formatter/OutputFormatterInterface.php

@@ -23,7 +23,7 @@ interface OutputFormatterInterface
     /**
      * Sets the decorated flag.
      *
-     * @param Boolean $decorated Whether to decorated the messages or not
+     * @param Boolean $decorated Whether to decorate the messages or not
      *
      * @api
      */

src/Symfony/Component/Console/Formatter/OutputFormatterStyle.php

@@ -79,6 +79,8 @@ public function __construct($foreground = null, $background = null, array $optio
      *
      * @param   string  $color  color name
      *
+     * @throws \InvalidArgumentException When the color name isn't defined
+     *
      * @api
      */
     public function setForeground($color = null)
@@ -105,6 +107,8 @@ public function setForeground($color = null)
      *
      * @param   string  $color  color name
      *
+     * @throws \InvalidArgumentException When the color name isn't defined
+     *
      * @api
      */
     public function setBackground($color = null)
@@ -131,6 +135,8 @@ public function setBackground($color = null)
      *
      * @param   string  $option     option name
      *
+     * @throws \InvalidArgumentException When the option name isn't defined
+     *
      * @api
      */
     public function setOption($option)
@@ -152,6 +158,9 @@ public function setOption($option)
      * Unsets some specific style option.
      *
      * @param   string  $option     option name
+     *
+     * @throws \InvalidArgumentException When the option name isn't defined
+     *
      */
     public function unsetOption($option)
     {
@@ -170,7 +179,7 @@ public function unsetOption($option)
     }
 
     /**
-     * Set multiple style options at once.
+     * Sets multiple style options at once.
      *
      * @param   array   $options
      */

src/Symfony/Component/Console/Formatter/OutputFormatterStyleInterface.php

@@ -55,7 +55,7 @@ function setOption($option);
     function unsetOption($option);
 
     /**
-     * Set multiple style options at once.
+     * Sets multiple style options at once.
      *
      * @param   array   $options
      */

src/Symfony/Component/Console/Helper/DialogHelper.php

@@ -25,11 +25,13 @@ class DialogHelper extends Helper
     /**
      * Asks a question to the user.
      *
-     * @param OutputInterface $output
+     * @param OutputInterface $output   An Output instance
      * @param string|array    $question The question to ask
      * @param string          $default  The default answer if none is given by the user
      *
      * @return string The user answer
+     *
+     * @throws \RuntimeException If there is no data to read in the input stream
      */
     public function ask(OutputInterface $output, $question, $default = null)
     {
@@ -47,9 +49,9 @@ public function ask(OutputInterface $output, $question, $default = null)
     /**
      * Asks a confirmation to the user.
      *
-     * The question will be asked until the user answer by nothing, yes, or no.
+     * The question will be asked until the user answers by nothing, yes, or no.
      *
-     * @param OutputInterface $output
+     * @param OutputInterface $output   An Output instance
      * @param string|array    $question The question to ask
      * @param Boolean         $default  The default answer if the user enters nothing
      *
@@ -76,15 +78,15 @@ public function askConfirmation(OutputInterface $output, $question, $default = t
      * validated data when the data is valid and throw an exception
      * otherwise.
      *
-     * @param OutputInterface $output
-     * @param string|array    $question
+     * @param OutputInterface $output    An Output instance
+     * @param string|array    $question  The question to ask
      * @param callback        $validator A PHP callback
-     * @param integer         $attempts Max number of times to ask before giving up (false by default, which means infinite)
+     * @param integer         $attempts  Max number of times to ask before giving up (false by default, which means infinite)
      * @param string          $default  The default answer if none is given by the user
      *
      * @return mixed
      *
-     * @throws \Exception When any of the validator returns an error
+     * @throws \Exception When any of the validators return an error
      */
     public function askAndValidate(OutputInterface $output, $question, $validator, $attempts = false, $default = null)
     {
@@ -118,7 +120,7 @@ public function setInputStream($stream)
     }
 
     /**
-     * Returns the helper's canonical name
+     * Returns the helper's canonical name.
      */
     public function getName()
     {

src/Symfony/Component/Console/Helper/FormatterHelper.php

@@ -66,7 +66,7 @@ public function formatBlock($messages, $style, $large = false)
     }
 
     /**
-     * Returns the length of a string, uses mb_strlen if it is available.
+     * Returns the length of a string, using mb_strlen if it is available.
      *
      * @param string $string The string to check its length
      *
@@ -86,7 +86,7 @@ private function strlen($string)
     }
 
     /**
-     * Returns the helper's canonical name
+     * Returns the helper's canonical name.
      *
      * @return string The canonical name of the helper
      */

src/Symfony/Component/Console/Helper/HelperSet.php

@@ -24,6 +24,8 @@ class HelperSet
     private $command;
 
     /**
+     * Constructor.
+     *
      * @param Helper[] $helpers An array of helper.
      */
     public function __construct(array $helpers = array())

src/Symfony/Component/Console/Input/ArgvInput.php

@@ -25,7 +25,7 @@
  *     $input = new ArgvInput($_SERVER['argv']);
  *
  * If you pass it yourself, don't forget that the first element of the array
- * is the name of the running program.
+ * is the name of the running application.
  *
  * When passing an argument to the constructor, be sure that it respects
  * the same rules as the argv one. It's almost always better to use the
@@ -57,7 +57,7 @@ public function __construct(array $argv = null, InputDefinition $definition = nu
             $argv = $_SERVER['argv'];
         }
 
-        // strip the program name
+        // strip the application name
         array_shift($argv);
 
         $this->tokens = $argv;
@@ -253,10 +253,10 @@ public function getFirstArgument()
     }
 
     /**
-     * Returns true if the raw parameters (not parsed) contains a value.
+     * Returns true if the raw parameters (not parsed) contain a value.
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The value(s) to look for in the raw parameters (can be an array)
      *
@@ -279,7 +279,7 @@ public function hasParameterOption($values)
      * Returns the value of a raw option (not parsed).
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The value(s) to look for in the raw parameters (can be an array)
      * @param mixed $default The default value to return if no result is found

src/Symfony/Component/Console/Input/ArrayInput.php

@@ -58,10 +58,10 @@ public function getFirstArgument()
     }
 
     /**
-     * Returns true if the raw parameters (not parsed) contains a value.
+     * Returns true if the raw parameters (not parsed) contain a value.
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The values to look for in the raw parameters (can be an array)
      *
@@ -88,7 +88,7 @@ public function hasParameterOption($values)
      * Returns the value of a raw option (not parsed).
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The value(s) to look for in the raw parameters (can be an array)
      * @param mixed $default The default value to return if no result is found
@@ -132,7 +132,7 @@ protected function parse()
      * @param string $shortcut The short option key
      * @param mixed  $value    The value for the option
      *
-     * @throws \RuntimeException When option given doesn't exist
+     * @throws \InvalidArgumentException When option given doesn't exist
      */
     private function addShortOption($shortcut, $value)
     {

src/Symfony/Component/Console/Input/InputDefinition.php

@@ -86,7 +86,7 @@ public function setArguments($arguments = array())
     }
 
     /**
-     * Add an array of InputArgument objects.
+     * Adds an array of InputArgument objects.
      *
      * @param InputArgument[] $arguments An array of InputArgument objects
      *
@@ -102,7 +102,7 @@ public function addArguments($arguments = array())
     }
 
     /**
-     * Add an InputArgument object.
+     * Adds an InputArgument object.
      *
      * @param InputArgument $argument An InputArgument object
      *
@@ -237,7 +237,7 @@ public function setOptions($options = array())
     }
 
     /**
-     * Add an array of InputOption objects.
+     * Adds an array of InputOption objects.
      *
      * @param InputOption[] $options An array of InputOption objects
      *
@@ -251,7 +251,7 @@ public function addOptions($options = array())
     }
 
     /**
-     * Add an InputOption object.
+     * Adds an InputOption object.
      *
      * @param InputOption $option An InputOption object
      *

src/Symfony/Component/Console/Input/InputInterface.php

@@ -26,10 +26,10 @@ interface InputInterface
     function getFirstArgument();
 
     /**
-     * Returns true if the raw parameters (not parsed) contains a value.
+     * Returns true if the raw parameters (not parsed) contain a value.
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The values to look for in the raw parameters (can be an array)
      *
@@ -41,7 +41,7 @@ function hasParameterOption($values);
      * Returns the value of a raw option (not parsed).
      *
      * This method is to be used to introspect the input parameters
-     * before it has been validated. It must be used carefully.
+     * before they have been validated. It must be used carefully.
      *
      * @param string|array $values The value(s) to look for in the raw parameters (can be an array)
      * @param mixed $default The default value to return if no result is found
@@ -58,7 +58,7 @@ function getParameterOption($values, $default = false);
     function bind(InputDefinition $definition);
 
     /**
-     * Validate if arguments given are correct.
+     * Validates if arguments given are correct.
      *
      * Throws an exception when not enough arguments are given.
      *
@@ -74,7 +74,7 @@ function validate();
     function getArguments();
 
     /**
-     * Get argument by name.
+     * Gets argument by name.
      *
      * @param string $name The name of the argument
      *
@@ -83,12 +83,14 @@ function getArguments();
     function getArgument($name);
 
     /**
+     * Returns all the given options merged with the default values.
+     *
      * @return array
      */
     function getOptions();
 
     /**
-     * Get an option by name.
+     * Gets an option by name.
      *
      * @param string $name The name of the option
      *

src/Symfony/Component/Console/Input/InputOption.php

@@ -79,7 +79,7 @@ public function __construct($name, $shortcut = null, $mode = null, $description
     }
 
     /**
-     * Returns the shortcut.
+     * Returns the option shortcut.
      *
      * @return string The shortcut
      */
@@ -89,7 +89,7 @@ public function getShortcut()
     }
 
     /**
-     * Returns the name.
+     * Returns the option name.
      *
      * @return string The name
      */
@@ -142,6 +142,8 @@ public function isArray()
      * Sets the default value.
      *
      * @param mixed $default The default value
+     *
+     * @throws \LogicException When incorrect default value is given
      */
     public function setDefault($default = null)
     {