Correcting and expanding documentation on console classes.

cake/console/libs/console_error_handler.php

@@ -51,8 +51,9 @@ class ConsoleErrorHandler extends ErrorHandler {
 	}
 
 /**
- * Handle a exception in the console environment.
+ * Handle a exception in the console environment. Prints a message to stderr.
  *
+ * @param Exception $exception The exception to handle
  * @return void
  */
 	public static function handleException(Exception $exception) {
@@ -67,6 +68,11 @@ class ConsoleErrorHandler extends ErrorHandler {
 /**
  * Handle errors in the console environment.
  *
+ * @param int $code Error code
+ * @param string $description Description of the error.
+ * @param string $file The file the error occurred in.
+ * @param int $line The line the error ocurrred on.
+ * @param array $context The backtrace of the error.
  * @return void
  */
 	public static function handleError($code, $description, $file = null, $line = null, $context = null) {
@@ -84,17 +90,4 @@ class ConsoleErrorHandler extends ErrorHandler {
 		}
 	}
 
-/**
- * undocumented function
- *
- * @return void
- */
-	public function render() {
-		$this->stderr->write(sprintf(
-			__("<error>Error:</error> %s\n%s"), 
-			$this->error->getMessage(), 
-			$this->error->getTraceAsString()
-		));
-	}
-
 }

cake/console/libs/console_input.php

@@ -33,7 +33,7 @@ class ConsoleInput {
 /**
  * Constructor
  *
- * @return void
+ * @param string $handle The location of the stream to use as input.
  */
 	public function __construct($handle = 'php://stdin') {
 		$this->_input = fopen($handle, 'r');

cake/console/libs/console_input_argument.php

@@ -25,8 +25,33 @@
  * @package cake.console
  */
 class ConsoleInputArgument {
+/**
+ * Name of the argument.
+ *
+ * @var string
+ */
+	protected $_name;
 
-	protected $_name, $_help, $_required, $_choices;
+/**
+ * Help string
+ *
+ * @var string
+ */
+	protected $_help;
+
+/**
+ * Is this option required?
+ *
+ * @var boolean
+ */
+	protected $_required;
+
+/**
+ * An array of valid choices for this argument.
+ *
+ * @var array
+ */
+	protected $_choices;
 
 /**
  * Make a new Input Argument
@@ -34,8 +59,7 @@ class ConsoleInputArgument {
  * @param mixed $name The long name of the option, or an array with all the properites.
  * @param string $help The help text for this option
  * @param boolean $required Whether this argument is required. Missing required args will trigger exceptions
- * @param arraty $choices Valid choices for this option.
- * @return void
+ * @param array $choices Valid choices for this option.
  */
 	public function __construct($name, $help = '', $required = false, $choices = array()) {
 		if (is_array($name) && isset($name['name'])) {
@@ -60,7 +84,7 @@ class ConsoleInputArgument {
 	}
 
 /**
- * Generate the help for this this argument.
+ * Generate the help for this argument.
  *
  * @param int $width The width to make the name of the option.
  * @return string 
@@ -125,7 +149,7 @@ class ConsoleInputArgument {
 	}
 
 /**
- * Append this argument to the passed in SimpleXml object.
+ * Append this arguments XML representation to the passed in SimpleXml object.
  *
  * @param SimpleXmlElement The parent element.
  * @return SimpleXmlElement The parent with this argument appended.

cake/console/libs/console_input_option.php

@@ -26,8 +26,47 @@
  * @package cake.console
  */
 class ConsoleInputOption {
+/**
+ * Name of the option
+ *
+ * @var string
+ */
+	protected $_name;
 
-	protected $_name, $_short, $_help, $_boolean, $_default, $_choices;
+/**
+ * Short (1 character) alias for the option.
+ *
+ * @var string
+ */
+	protected $_short;
+
+/**
+ * Help text for the option.
+ *
+ * @var string
+ */
+	protected $_help;
+
+/**
+ * Is the option a boolean option.  Boolean options do not consume a parameter.
+ *
+ * @var boolean
+ */
+	protected $_boolean;
+
+/**
+ * Default value for the option
+ *
+ * @var mixed
+ */
+	protected $_default;
+
+/**
+ * An array of choices for the option.
+ *
+ * @var array
+ */
+	protected $_choices;
 
 /**
  * Make a new Input Option
@@ -37,8 +76,7 @@ class ConsoleInputOption {
  * @param string $help The help text for this option
  * @param boolean $boolean Whether this option is a boolean option.  Boolean options don't consume extra tokens
  * @param string $default The default value for this option.
- * @param arraty $choices Valid choices for this option.
- * @return void
+ * @param array $choices Valid choices for this option.
  */
 	public function __construct($name, $short = null, $help = '', $boolean = false, $default = '', $choices = array()) {
 		if (is_array($name) && isset($name['name'])) {
@@ -117,7 +155,7 @@ class ConsoleInputOption {
 /**
  * Get the default value for this option
  *
- * @return void
+ * @return mixed
  */
 	public function defaultValue() {
 		return $this->_default;

cake/console/libs/console_input_subcommand.php

@@ -27,15 +27,34 @@
  */
 class ConsoleInputSubcommand {
 
-	protected $_name, $_help, $_parser;
+/**
+ * Name of the subcommand
+ *
+ * @var string
+ */
+	protected $_name;
+
+/**
+ * Help string for the subcommand
+ *
+ * @var string
+ */
+	protected $_help; 
+
+/**
+ * The ConsoleOptionParser for this subcommand.
+ *
+ * @var ConsoleOptionParser
+ */
+	protected $_parser;
 
 /**
  * Make a new Subcommand
  *
  * @param mixed $name The long name of the subcommand, or an array with all the properites.
  * @param string $help The help text for this option
- * @param ConsoleOptionParser $parser A parser for this subcommand.
- * @return void
+ * @param mixed $parser A parser for this subcommand. Either a ConsoleOptionParser, or an array that can be 
+ *   used with ConsoleOptionParser::buildFromArray()
  */
 	public function __construct($name, $help = '', $parser = null) {
 		if (is_array($name) && isset($name['name'])) {

cake/console/libs/console_option_parser.php

@@ -88,7 +88,7 @@ class ConsoleOptionParser {
  * preceeded by one - and are only one character long.  They usually match with a long option,
  * and provide a more terse alternative.
  *
- * #### Using Options
+ * ### Using Options
  *
  * Options can be defined with both long and short forms.  By using `$parser->addOption()`
  * you can define new options.  The name of the option is used as its long form, and you
@@ -195,7 +195,7 @@ class ConsoleOptionParser {
 	}
 
 /**
- * Get or set the command name for shell/task
+ * Get or set the command name for shell/task.
  *
  * @param string $text The text to set, or null if you want to read
  * @return mixed If reading, the value of the command. If setting $this will be returned
@@ -209,7 +209,7 @@ class ConsoleOptionParser {
 	}
 
 /**
- * Get or set the description text for shell/task
+ * Get or set the description text for shell/task.
  *
  * @param mixed $text The text to set, or null if you want to read. . If an array the text will be imploded with "\n"
  * @return mixed If reading, the value of the description. If setting $this will be returned
@@ -247,7 +247,7 @@ class ConsoleOptionParser {
  * Add an option to the option parser. Options allow you to define optional or required
  * parameters for your console application. Options are defined by the parameters they use.
  *
- * ### Params
+ * ### Options
  *
  * - `short` - The single letter variant for this option, leave undefined for none.
  * - `help` - Help text for this option.  Used when generating help for the option.
@@ -260,11 +260,12 @@ class ConsoleOptionParser {
  * - `choices` A list of valid choices for this option.  If left empty all values are valid..
  *   An exception will be raised when parse() encounters an invalid value.
  *
- * @param string $name The long name you want to the value to be parsed out as when options are parsed.
+ * @param mixed $name The long name you want to the value to be parsed out as when options are parsed.
+ *   Will also accept an instance of ConsoleInputOption
  * @param array $params An array of parameters that define the behavior of the option
  * @return returns $this.
  */
-	public function addOption($name, $params = array()) {
+	public function addOption($name, $options = array()) {
 		if (is_object($name) && $name instanceof ConsoleInputOption) {
 			$option = $name;
 			$name = $option->name();
@@ -277,7 +278,7 @@ class ConsoleOptionParser {
 				'boolean' => false,
 				'choices' => array()
 			);
-			$options = array_merge($defaults, $params);
+			$options = array_merge($defaults, $options);
 			$option = new ConsoleInputOption($options);
 		}
 		$this->_options[$name] = $option;
@@ -300,7 +301,7 @@ class ConsoleOptionParser {
  * - `choices` A list of valid choices for this argument.  If left empty all values are valid..
  *   An exception will be raised when parse() encounters an invalid value.
  *
- * @param string $name The name of the argument.
+ * @param mixed $name The name of the argument.  Will also accept an instance of ConsoleInputArgument
  * @param array $params Parameters for the argument, see above.
  * @return $this.
  */
@@ -357,21 +358,20 @@ class ConsoleOptionParser {
 
 /**
  * Append a subcommand to the subcommand list.
- * Subcommands are usually methods on your Shell, but can also be used to document
- * Tasks
+ * Subcommands are usually methods on your Shell, but can also be used to document Tasks.
  *
- * ### Params
+ * ### Options
  *
  * - `help` - Help text for the subcommand.
  * - `parser` - A ConsoleOptionParser for the subcommand.  This allows you to create method
  *    specific option parsers.  When help is generated for a subcommand, if a parser is present
  *    it will be used.
  *
- * @param string $name Name of the subcommand
+ * @param mixed $name Name of the subcommand. Will also accept an instance of ConsoleInputSubcommand
  * @param array $params Array of params, see above.
  * @return $this.
  */
-	public function addSubcommand($name, $params = array()) {
+	public function addSubcommand($name, $options = array()) {
 		if (is_object($name) && $name instanceof ConsoleInputSubcommand) {
 			$command = $name;
 			$name = $command->name();
@@ -381,7 +381,7 @@ class ConsoleOptionParser {
 				'help' => '',
 				'parser' => null
 			);
-			$options = array_merge($defaults, $params);
+			$options = array_merge($defaults, $options);
 			$command = new ConsoleInputSubcommand($options);
 		}
 		$this->_subcommands[$name] = $command;

cake/console/libs/console_output.php

@@ -21,7 +21,7 @@
  * Object wrapper for outputing information from a shell application.
  * Can be connected to any stream resource that can be used with fopen()
  * 
- * Can generate colourzied output on consoles that support it. There are a few 
+ * Can generate colourized output on consoles that support it. There are a few 
  * built in styles
  *
  * - `error` Error messages.
@@ -143,8 +143,8 @@ class ConsoleOutput {
  *
  * Checks for a pretty console enviornment.  Ansicon allows pretty consoles
  * on windows, and is supported.
- *
- * @return void
+ * 
+ * @param string $stream The identifier of the stream to write output to.
  */
 	public function __construct($stream = 'php://stdout') {
 		$this->_output = fopen($stream, 'w');
@@ -156,7 +156,7 @@ class ConsoleOutput {
 
 /**
  * Outputs a single or multiple messages to stdout. If no parameters
- * are passed outputs just a newline.
+ * are passed, outputs just a newline.
  *
  * @param mixed $message A string or a an array of strings to output
  * @param integer $newlines Number of newlines to append
@@ -216,7 +216,7 @@ class ConsoleOutput {
 	}
 
 /**
- * Writes a message to the output stream
+ * Writes a message to the output stream.
  *
  * @param string $message Message to write.
  * @return boolean success

cake/console/libs/help_formatter.php

@@ -12,9 +12,6 @@
  *
  * @copyright     Copyright 2005-2010, Cake Software Foundation, Inc. (http://cakefoundation.org)
  * @link          http://cakephp.org CakePHP(tm) Project
- * @package       cake
- * @subpackage    cake.cake.console
- * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
 App::import('Core', 'String', false);
@@ -28,12 +25,14 @@ App::import('Core', 'String', false);
  *
  * Xml output is useful for intergration with other tools like IDE's or other build tools.
  *
+ * @package    cake.console
+ * @since      CakePHP(tm) v 2.0
  */
 class HelpFormatter {
 /**
  * Build the help formatter for a an OptionParser
  *
- * @return void
+ * @param ConsoleOptionParser $parser The option parser help is being generated for.
  */
 	public function __construct(ConsoleOptionParser $parser) {
 		$this->_parser = $parser;