[2.0] Added docblocks

lib/Doctrine/ORM/Tools/Cli.php

@@ -22,6 +22,8 @@
 namespace Doctrine\ORM\Tools;
 
 use Doctrine\Common\Util\Inflector,
+    Doctrine\ORM\Tools\Cli\AbstractPrinter,
+    Doctrine\ORM\Tools\Cli\AbstractTask,
     Doctrine\ORM\Tools\Cli\Printer;
 
 /**
@@ -30,7 +32,7 @@ use Doctrine\Common\Util\Inflector,
  * To include a new Task support, create a task:
  *
  *     [php]
- *     class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\Task {
+ *     class MyProject\Tools\Cli\Tasks\MyTask extends Doctrine\ORM\Tools\Cli\AbstractTask {
  *         public function run();
  *         public function basicHelp();
  *         public function extendedHelp();
@@ -59,7 +61,12 @@ use Doctrine\Common\Util\Inflector,
 class Cli
 {
     /**
-     * @var Cli\AbstractPrinter CLI Printer instance
+     * @var ORM\Configuration Configuration
+     */
+    //private $_configuration = null;
+    
+    /**
+     * @var AbstractPrinter CLI Printer instance
      */
     private $_printer = null;
     
@@ -68,8 +75,12 @@ class Cli
      */
     private $_tasks = array();
     
-
+    /**
-    public function __construct($printer = null)
+     * The CLI processor of tasks
+     *
+     * @param AbstractPrinter $printer CLI Output printer
+     */
+    public function __construct(AbstractPrinter $printer = null)
     {
         //$this->_printer = new Printer\Normal();
         $this->_printer = $printer ?: new Printer\AnsiColor();
@@ -83,6 +94,18 @@ class Cli
         ));
     }
     
+    /**
+     * Add a collection of tasks to the CLI.
+     * To include them, just call the method with the following structure:
+     *
+     *    [php]
+     *    $cli->addTasks(array(
+     *        'my-custom-task' => 'MyProject\Cli\Tasks\MyCustomTask',
+     *        ...
+     *    ));
+     *
+     * @param array $tasks CLI Tasks to be included
+     */
     public function addTasks($tasks)
     {
         foreach ($tasks as $name => $class) {
@@ -90,6 +113,16 @@ class Cli
         }
     }
     
+    /**
+     * Add a single task to CLI.
+     * Example of inclusion support to a single task:
+     *
+     *     [php]
+     *     $cli->addTask('my-custom-task', 'MyProject\Cli\Tasks\MyCustomTask');
+     *
+     * @param string $name CLI Task name
+     * @param string $class CLI Task class (FQCN - Fully Qualified Class Name)
+     */
     public function addTask($name, $class)
     {
         // Convert $name into a class equivalent 
@@ -99,6 +132,12 @@ class Cli
         $this->_tasks[$name] = $class;
     }
     
+    /**
+     * Processor of CLI Tasks. Handles multiple task calls, instantiate
+     * respective classes and run them.
+     *
+     * @param array $args CLI Arguments
+     */
     public function run($args = array())
     {
         // Remove script file argument
@@ -121,18 +160,16 @@ class Cli
                 $taskName = $this->_processTaskName($taskData['name']);
                 $taskArguments = $taskData['args'];
                 
-                // Always include supported Tasks as argument
-                $taskArguments['availableTasks'] = $this->_tasks;
-        
                 // Check if task exists
                 if (isset($this->_tasks[$taskName]) && class_exists($this->_tasks[$taskName], true)) {
                     // Instantiate and execute the task
                     $task = new $this->_tasks[$taskName]();
+                    $task->setAvailableTasks($this->_tasks);
                     $task->setPrinter($this->_printer);
                     $task->setArguments($taskArguments);
                 
                     if (isset($taskArguments['help']) && $taskArguments['help']) {
-                        $task->extendedHelp(); // User explicitly asked for task help
+                        $task->extendedHelp(); // User explicitly asked for help option
                     } else if ($this->_isTaskValid($task)) {
                         $task->run();
                     } else {
@@ -248,9 +285,15 @@ class Cli
         return $preparedArgs;
     }
     
-    private function _isTaskValid($task)
+    /**
+     * Checks if CLI Task is valid based on given arguments.
+     *
+     * @param AbstractTask $task CLI Task instance
+     */
+    private function _isTaskValid(AbstractTask $task)
     {
-        // TODO: Should we check for required and optional arguments here?
+        // TODO: Should we change the behavior and check for 
+        // required and optional arguments here?
         return $task->validate();
     }
 }

lib/Doctrine/ORM/Tools/Cli/AbstractPrinter.php

@@ -21,14 +21,41 @@
  
 namespace Doctrine\ORM\Tools\Cli;
 
+/**
+ * CLI Output Printer.
+ * Abstract class responsable to provide basic methods to support output 
+ * styling and excerpt limited by output margin.
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 abstract class AbstractPrinter
 {
+    /**
+     * @var resource Output Stream
+     */
     protected $_stream;
 
+    /**
+     * @var integer Maximum column size
+     */
     protected $_maxColumnSize;
 
+    /**
+     * @var array Array of Styles
+     */
     protected $_styles;
 
+    /**
+     * Creates an instance of Printer
+     *
+     * @param resource $stream Output Stream
+     */
     public function __construct($stream = STDOUT)
     {
         $this->_stream = $stream;
@@ -37,6 +64,10 @@ abstract class AbstractPrinter
         $this->_initStyles();
     }
     
+    /**
+     * Initializes Printer Styles
+     *
+     */
     protected function _initStyles()
     {
         // Defines base styles
@@ -49,6 +80,18 @@ abstract class AbstractPrinter
         ));
     }
     
+    /**
+     * Add a collection of styles to the Printer.
+     * To include them, just call the method with the following structure:
+     *
+     *    [php]
+     *    $printer->addStyles(array(
+     *        'ERROR' => new Style('BLACK', 'DEFAULT', array('BOLD' => true)),
+     *        ...
+     *    ));
+     *
+     * @param array $tasks CLI Tasks to be included
+     */
     public function addStyles($styles)
     {
         foreach ($styles as $name => $style) {
@@ -56,11 +99,26 @@ abstract class AbstractPrinter
         }
     }
     
+    /**
+     * Add a single Style to Printer.
+     * Example of inclusion to support a new Style:
+     *
+     *     [php]
+     *     $printer->addStyle('ERROR', new Style('BLACK', 'DEFAULT', array('BOLD' => true)));
+     *
+     * @param string $name Style name
+     * @param Style $style Style instance
+     */
     public function addStyle($name, Style $style)
     {
         $this->_styles[strtoupper($name)] = $style;
     }
     
+    /**
+     * Retrieves a defined Style.
+     *
+     * @return Style
+     */
     public function getStyle($name)
     {
         $name = strtoupper($name);

lib/Doctrine/ORM/Tools/Cli/AbstractTask.php

@@ -21,36 +21,140 @@
  
 namespace Doctrine\ORM\Tools\Cli;
 
+/**
+ * CLI Task.
+ * Provides basic methods and requires implementation of methods that
+ * each task should implement in order to correctly work.
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 abstract class AbstractTask
 {
+    /**
+     * @var AbstractPrinter CLI Output Printer
+     */
     protected $_printer;
+    
+    /**
+     * @var array CLI argument options
+     */
     protected $_arguments;
     
+    /**
+     * @var array Available CLI tasks
+     */
+    protected $_availableTasks;
+    
+    /**
+     * Defines a CLI Output Printer
+     *
+     * @param AbstractPrinter CLI Output Printer
+     */
     public function setPrinter(AbstractPrinter $printer)
     {
         $this->_printer = $printer;
     }
 
+    /**
+     * Retrieves currently used CLI Output Printer
+     *
+     * @return AbstractPrinter
+     */
     public function getPrinter()
     {
         return $this->_printer;
     }
     
+    /**
+     * Defines the CLI arguments
+     *
+     * @param array CLI argument options
+     */
     public function setArguments($arguments)
     {
         $this->_arguments = $arguments;
     }
     
+    /**
+     * Retrieves current CLI arguments
+     *
+     * @return array
+     */
     public function getArguments()
     {
         return $this->_arguments;
     }
     
+    /**
+     * Defines the available CLI tasks
+     *
+     * @param array Available CLI tasks
+     */
+    public function setAvailableTasks($availableTasks)
+    {
+        $this->_availableTasks = $availableTasks;
+    }
+    
+    /**
+     * Retrieves the available CLI tasks
+     *
+     * @return array
+     */
+    public function getAvailableTasks()
+    {
+        return $this->_availableTasks;
+    }
+    
+    /**
+     * Expose to CLI Output Printer the extended help of the given task.
+     * This means it should detail all parameters, options and the meaning
+     * of each one.
+     * This method is executed when user types in CLI the following command:
+     *
+     *     [bash]
+     *     ./doctrine task --help
+     *
+     */
     abstract public function extendedHelp();
     
+    /**
+     * Expose to CLI Output Printer the basic help of the given task.
+     * This means it should only expose the basic task call. It is also
+     * executed when user calls the global help; so this means it should
+     * not pollute the Printer.
+     * Basic help exposure is displayed when task does not pass the validate
+     * (which means when user does not type the required options or when given
+     * options are invalid, ie: invalid option), or when user requests to have
+     * description of all available tasks.
+     * This method is executed when user uses the following commands:
+     *
+     *     [bash]
+     *     ./doctrine task --invalid-option
+     *     ./doctrine --help
+     *
+     */
     abstract public function basicHelp();
     
+    /**
+     * Assures the given arguments matches with required/optional ones.
+     * This method should be used to introspect arguments to check for
+     * missing required arguments and also for invalid defined options.
+     *
+     * @return boolean
+     */
     abstract public function validate();
     
+    /**
+     * Safely execution of task.
+     * Each CLI task should implement this as normal flow execution of
+     * what is supposed to do.
+     *
+     */
     abstract public function run();
 }

lib/Doctrine/ORM/Tools/Cli/Printer/AnsiColor.php

@@ -24,42 +24,65 @@ namespace Doctrine\ORM\Tools\Cli\Printer;
 use Doctrine\ORM\Tools\Cli\AbstractPrinter,
     Doctrine\ORM\Tools\Cli\Style;
 
+/**
+ * CLI Output Printer for ANSI Color terminal
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class AnsiColor extends AbstractPrinter
 {
+    /**
+     * @inheritdoc
+     */
     protected function _initStyles()
     {
         $this->addStyles(array(
-            'ERROR'   => new Style('RED', 'WHITE', array('BOLD' => true)),
+            'ERROR'   => new Style('WHITE', 'RED', array('BOLD' => true)),
             'INFO'    => new Style('GREEN', 'DEFAULT', array('BOLD' => true)),
-            'COMMENT' => new Style('YELLOW', 'DEFAULT'),
+            'COMMENT' => new Style('DEFAULT', 'YELLOW'),
             'HEADER'  => new Style('DEFAULT', 'DEFAULT', array('BOLD' => true)),
             'NONE'    => new Style(),
         ));
     }
     
+    /**
+     * @inheritdoc
+     */
     public function format($message, Style $style)
     {
         if ( ! $this->_supportsColor()) {
             return $message;
         }
         
-        $str = $this->getForegroundString($style->getForeground()) 
+        $str = $this->_getForegroundString($style->getForeground()) 
-             . $this->getBackgroundString($style->getBackground()) 
+             . $this->_getBackgroundString($style->getBackground()) 
-             . $this->getOptionsString($style->getOptions());
+             . $this->_getOptionsString($style->getOptions());
         $styleSet = ($str != '');
         
         return $str . $message . ($styleSet ? chr(27) . '[0m' : '');
     }
     
-    public function getForegroundString($foreground)
+    /**
+     * Retrieves the ANSI string representation of requested color name
+     *
+     * @param string $background Background color name
+     * @return string
+     */
+    protected function _getBackgroundString($background)
     {
-        if (empty($foreground)) {
+        if (empty($background)) {
             return '';
         }
     
         $esc = chr(27);
         
-        switch ($foreground) {
+        switch ($background) {
             case 'BLACK': 
                 return $esc . '[40m';
             case 'RED': 
@@ -82,15 +105,21 @@ class AnsiColor extends AbstractPrinter
         }
     }
  
-    public function getBackgroundString($background)
+    /**
+     * Retrieves the ANSI string representation of requested color name
+     *
+     * @param string $foreground Foreground color name
+     * @return string
+     */
+    protected function _getForegroundString($foreground)
     {
-        if (empty($background)) {
+        if (empty($foreground)) {
             return '';
         }
     
         $esc = chr(27);
         
-        switch ($background) {
+        switch ($foreground) {
             case 'BLACK': 
                 return $esc . '[30m';
             case 'RED': 
@@ -115,7 +144,13 @@ class AnsiColor extends AbstractPrinter
         }
     }
     
-    public function getOptionsString($options)
+    /**
+     * Retrieves the ANSI string representation of requested options
+     *
+     * @param array $options Options
+     * @return string
+     */
+    protected function _getOptionsString($options)
     {
         if (empty($options)) {
             return '';
@@ -157,7 +192,11 @@ class AnsiColor extends AbstractPrinter
         return $str;
     }
     
-    
+    /**
+     * Checks if the current Output Stream supports ANSI Colors
+     *
+     * @return boolean
+     */
     private function _supportsColor()
     {
         return DIRECTORY_SEPARATOR != '\\' && 

lib/Doctrine/ORM/Tools/Cli/Printer/Normal.php

@@ -24,8 +24,22 @@ namespace Doctrine\ORM\Tools\Cli\Printer;
 use Doctrine\ORM\Tools\Cli\AbstractPrinter,
     Doctrine\ORM\Tools\Cli\Style;
 
+/**
+ * CLI Output Printer for Normal terminal
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class Normal extends AbstractPrinter
 {
+    /**
+     * @inheritdoc
+     */
     public function format($message, Style $style)
     {
         return $message;

lib/Doctrine/ORM/Tools/Cli/Style.php

@@ -21,14 +21,39 @@
  
 namespace Doctrine\ORM\Tools\Cli;
 
+/**
+ * CLI Output Style
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class Style
 {
+    /**
+     * @var string Background color
+     */
     private $_background;
     
+    /**
+     * @var string Foreground color
+     */    
     private $_foreground;
     
+    /**
+     * @var array Formatting options
+     */
     private $_options = array();
     
+    /**
+     * @param string $foreground Foreground color name
+     * @param string $background Background color name
+     * @param array $options Formatting options
+     */
     public function __construct($foreground = null, $background = null, $options = array())
     {
         $this->_foreground = strtoupper($foreground);
@@ -36,16 +61,31 @@ class Style
         $this->_options = $options;
     }
     
+    /**
+     * Retrieves the foreground color name
+     *
+     * @return string
+     */
     public function getForeground()
     {
         return $this->_foreground;
     }
     
+    /**
+     * Retrieves the background color name
+     *
+     * @return string
+     */
     public function getBackground()
     {
         return $this->_background;
     }
     
+    /**
+     * Retrieves the formatting options
+     *
+     * @return string
+     */
     public function getOptions()
     {
         return $this->_options;

lib/Doctrine/ORM/Tools/Cli/Task/Help.php

@@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task;
 
 use Doctrine\ORM\Tools\Cli\AbstractTask;
 
+/**
+ * CLI Task to display available commands help
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class Help extends AbstractTask
 {
+    /**
+     * @inheritdoc
+     */
     public function extendedHelp()
     {
         $this->getPrinter()->write('help extended help' . PHP_EOL, 'HEADER');
@@ -34,6 +48,9 @@ class Help extends AbstractTask
         $this->getPrinter()->write('help extended help' . PHP_EOL, 'NONE');
     }
 
+    /**
+     * @inheritdoc
+     */
     public function basicHelp()
     {
         $this->getPrinter()->write('help basic help' . PHP_EOL, 'HEADER');
@@ -42,12 +59,19 @@ class Help extends AbstractTask
         $this->getPrinter()->write('help basic help' . PHP_EOL, 'COMMENT');
         $this->getPrinter()->write('help basic help' . PHP_EOL, 'NONE');
     }
-    
+
+    /**
+     * @inheritdoc
+     */    
     public function validate()
     {
         return true;
     }
 
+    /**
+     * Exposes the available tasks
+     *
+     */
     public function run()
     {
         $this->getPrinter()->write('help run' . PHP_EOL, 'HEADER');

lib/Doctrine/ORM/Tools/Cli/Task/Version.php

@@ -23,8 +23,22 @@ namespace Doctrine\ORM\Tools\Cli\Task;
 
 use Doctrine\ORM\Tools\Cli\AbstractTask;
 
+/**
+ * CLI Task to display the doctrine version
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision$
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class Version extends AbstractTask
 {
+    /**
+     * @inheritdoc
+     */
     public function extendedHelp()
     {
         $this->getPrinter()->write('version extended help' . PHP_EOL, 'HEADER');
@@ -34,6 +48,9 @@ class Version extends AbstractTask
         $this->getPrinter()->write('version extended help' . PHP_EOL, 'NONE');
     }
 
+    /**
+     * @inheritdoc
+     */
     public function basicHelp()
     {
         $this->getPrinter()->write('version basic help' . PHP_EOL, 'HEADER');
@@ -43,11 +60,18 @@ class Version extends AbstractTask
         $this->getPrinter()->write('version basic help' . PHP_EOL, 'NONE');
     }
     
+    /**
+     * @inheritdoc
+     */
     public function validate()
     {
         return true;
     }
 
+    /**
+     * Displays the current version of Doctrine
+     *
+     */
     public function run()
     {
         $this->getPrinter()->write('version run' . PHP_EOL, 'HEADER');