Moved common help parsing code into HelpParser. Action methods now have default implementation.

framework/console/Action.php

@@ -22,25 +22,27 @@ use yii\helpers\Console;
 class Action extends \yii\base\Action
 {
     /**
-     * Returns a short description (one line) of information about the action.
+     * Returns one-line short summary describing this action.
      *
-     * The default implementation returns help information retrieved from the PHPDoc comments.
+     * You may override this method to return customized summary.
+     * The default implementation returns first line from the PHPDoc comment.
      *
      * @return string
      */
-    public function getDescription()
+    public function getHelpSummary()
     {
-        return null;
+        return HelpParser::getSummary(new \ReflectionClass($this));
     }
 
     /**
-     * Returns help information for the action.
+     * Returns help information for this action.
      *
-     * The default implementation returns help information retrieved from the PHPDoc comments.
+     * You may override this method to return customized help.
+     * The default implementation returns help information retrieved from the PHPDoc comment.
      * @return string
      */
     public function getHelp()
     {
-        return null;
+        return HelpParser::getDescriptionForConsole(new \ReflectionClass($this));
     }
 }

framework/console/Controller.php

@@ -9,6 +9,7 @@ namespace yii\console;
 
 use Yii;
 use yii\base\Action;
+use yii\base\InlineAction;
 use yii\base\InvalidRouteException;
 use yii\helpers\Console;
 
@@ -56,7 +57,7 @@ class Controller extends \yii\base\Controller
      */
     public function isColorEnabled($stream = \STDOUT)
     {
-        return $this->color ===  null ? Console::streamSupportsAnsiColors($stream) : $this->color;
+        return $this->color === null ? Console::streamSupportsAnsiColors($stream) : $this->color;
     }
 
     /**
@@ -99,7 +100,7 @@ class Controller extends \yii\base\Controller
      */
     public function bindActionParams($action, $params)
     {
-        if ($action instanceof \yii\base\InlineAction) {
+        if ($action instanceof InlineAction) {
             $method = new \ReflectionMethod($this, $action->actionMethod);
         } else {
             $method = new \ReflectionMethod($action, 'run');
@@ -275,67 +276,69 @@ class Controller extends \yii\base\Controller
     }
 
     /**
-     * Returns a short description (one line) of information about this controller or it's action (if specified).
+     * Returns one-line short summary describing this controller.
      *
-     * You may override this method to return customized description.
-     * The default implementation returns help information retrieved from the PHPDoc comments
-     * of the controller class.
+     * You may override this method to return customized summary.
+     * The default implementation returns first line from the PHPDoc comment.
      *
-     * @param string $actionID action to get description for. null means overall controller description.
      * @return string
      */
-    public function getDescription($actionID = null)
+    public function getHelpSummary()
     {
-        $action = null;
-        if ($actionID === null) {
-            $class = new \ReflectionClass($this);
+        return HelpParser::getSummary(new \ReflectionClass($this));
+    }
+
+    /**
+     * Returns one-line short summary describing this controller action.
+     *
+     * You may override this method to return customized summary.
+     * The default implementation returns first line from the PHPDoc comment.
+     *
+     * @param string $actionID action to get summary for
+     * @return string
+     */
+    public function getActionHelpSummary($actionID)
+    {
+        $action = $this->createAction($actionID);
+        if ($action instanceof InlineAction) {
+            $class = new \ReflectionMethod($this, $action->actionMethod);
         } else {
-            $action = $this->createAction($actionID);
-            if ($action instanceof \yii\base\InlineAction) {
-                $class = new \ReflectionMethod($this, $action->actionMethod);
-            } else {
-                $class = new \ReflectionClass($action);
-            }
+            $class = new \ReflectionClass($action);
         }
 
-        $docLines = preg_split('~\R~', $class->getDocComment());
-        if (isset($docLines[1])) {
-            return trim($docLines[1], ' *');
-        }
-        return '';
+        return HelpParser::getSummary($class);
     }
 
     /**
-     * Returns help information for this controller or it's action (if specified).
+     * Returns help information for this controller.
      *
      * You may override this method to return customized help.
-     * The default implementation returns help information retrieved from the PHPDoc comments
-     * of the controller class.
-     * @param string $actionID action to get help for. null means overall controller help.
+     * The default implementation returns help information retrieved from the PHPDoc comment.
      * @return string
      */
-    public function getHelp($actionID = null)
+    public function getHelp()
     {
-        $action = null;
-        if ($actionID === null) {
-            $class = new \ReflectionClass($this);
-        } else {
-            $action = $this->createAction($actionID);
+        return HelpParser::getFull(new \ReflectionClass($this));
+    }
 
-            if ($action instanceof \yii\base\InlineAction) {
-                $class = new \ReflectionMethod($this, $action->actionMethod);
-            } else {
-                $class = new \ReflectionClass($action);
-            }
-        }
+    /**
+     * Returns help information for this controller action.
+     *
+     * You may override this method to return customized help.
+     * The default implementation returns help information retrieved from the PHPDoc comment.
+     * @param string $actionID action to get help for
+     * @return string
+     */
+    public function getActionHelp($actionID)
+    {
+        $action = $this->createAction($actionID);
 
-        $comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
-        if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
-            $comment = trim(substr($comment, 0, $matches[0][1]));
-        }
-        if ($comment !== '') {
-            return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
+        if ($action instanceof InlineAction) {
+            $class = new \ReflectionMethod($this, $action->actionMethod);
+        } else {
+            $class = new \ReflectionClass($action);
         }
-        return '';
+
+        return HelpParser::getFull($class);
     }
 }

framework/console/HelpParser.php

+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\console;
+
+use yii\helpers\Console;
+
+/**
+ * HelpParser contains methods used to get help information from phpDoc.
+ *
+ * @author Alexander Makarov <sam@rmcreative.ru>
+ * @since 2.0
+ */
+class HelpParser
+{
+    /**
+     * Returns the first line of docblock.
+     *
+     * @param \Reflector $reflector
+     * @return string
+     */
+    public static function getSummary(\Reflector $reflector)
+    {
+        $docLines = preg_split('~\R~', $reflector->getDocComment());
+        if (isset($docLines[1])) {
+            return trim($docLines[1], ' *');
+        }
+        return '';
+    }
+
+    /**
+     * Returns full description from the docblock.
+     *
+     * @param \Reflector $reflector
+     * @return string
+     */
+    public static function getFull(\Reflector $reflector)
+    {
+        $comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($reflector->getDocComment(), '/'))), "\r", '');
+        if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
+            $comment = trim(substr($comment, 0, $matches[0][1]));
+        }
+        if ($comment !== '') {
+            return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment)));
+        }
+        return '';
+    }
+} 
\ No newline at end of file

framework/console/controllers/HelpController.php

@@ -9,6 +9,7 @@ namespace yii\console\controllers;
 
 use Yii;
 use yii\base\Application;
+use yii\base\InlineAction;
 use yii\console\Action;
 use yii\console\Controller;
 use yii\console\Exception;
@@ -61,7 +62,7 @@ class HelpController extends Controller
 
             $actions = $this->getActions($controller);
             if ($actionID !== '' || count($actions) === 1 && $actions[0] === $controller->defaultAction) {
-                $this->getActionHelp($controller, $actionID);
+                $this->getControllerActionHelp($controller, $actionID);
             } else {
                 $this->getControllerHelp($controller);
             }
@@ -94,7 +95,8 @@ class HelpController extends Controller
             $result = Yii::$app->createController($command);
             if ($result !== false) {
                 list($controller, $actionID) = $result;
-                $description = $controller->getDescription();
+                /** @var Controller $controller */
+                $description = $controller->getHelpSummary();
             }
 
             $descriptions[$command] = $description;
@@ -253,10 +255,10 @@ class HelpController extends Controller
         $action = $controller->createAction($actionID);
 
         if ($action instanceof Action) {
-            $description = $action->getDescription();
+            $description = $action->getHelpSummary();
         }
         if ($description === null) {
-            $description = $controller->getDescription($actionID);
+            $description = $controller->getActionHelpSummary($actionID);
         }
         return $description;
     }
@@ -267,7 +269,7 @@ class HelpController extends Controller
      * @param string $actionID action ID
      * @throws Exception if the action does not exist
      */
-    protected function getActionHelp($controller, $actionID)
+    protected function getControllerActionHelp($controller, $actionID)
     {
         $action = $controller->createAction($actionID);
         if ($action === null) {
@@ -276,9 +278,10 @@ class HelpController extends Controller
             ]));
         }
         $description = null;
-        if ($action instanceof \yii\base\InlineAction) {
+        if ($action instanceof InlineAction) {
             $method = new \ReflectionMethod($controller, $action->actionMethod);
         } else {
+            /** @var Action $action */
             $description = $action->getHelp();
             $method = new \ReflectionMethod($action, 'run');
         }
@@ -287,7 +290,7 @@ class HelpController extends Controller
         $options = $this->getOptionHelps($controller, $actionID);
 
         if ($description === null) {
-            $description = $controller->getHelp($actionID);
+            $description = $controller->getActionHelp($actionID);
         }
         if ($description !== '') {
             $this->stdout("\nDESCRIPTION\n", Console::BOLD);