Refactored help system. [skip ci]

framework/console/Action.php

@@ -1,48 +0,0 @@
-<?php
-/**
- * @link http://www.yiiframework.com/
- * @copyright Copyright (c) 2008 Yii Software LLC
- * @license http://www.yiiframework.com/license/
- */
-
-namespace yii\console;
-
-use Yii;
-use yii\helpers\Console;
-
-/**
- * Action is the base class for all controller action classes.
- *
- * @inheritdoc
- * @property \yii\console\Controller $controller
- *
- * @author Carsten Brandt <mail@cebe.cc>
- * @since 2.0
- */
-class Action extends \yii\base\Action
-{
-    /**
-     * Returns one-line short summary describing this action.
-     *
-     * You may override this method to return customized summary.
-     * The default implementation returns first line from the PHPDoc comment.
-     *
-     * @return string
-     */
-    public function getHelpSummary()
-    {
-        return HelpParser::getSummary(new \ReflectionClass($this));
-    }
-
-    /**
-     * Returns help information for this action.
-     *
-     * 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 HelpParser::getDetail(new \ReflectionClass($this));
-    }
-}

framework/console/Controller.php

@@ -288,27 +288,6 @@ class Controller extends \yii\base\Controller
         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 {
-            $class = new \ReflectionClass($action);
-        }
-
-        return HelpParser::getSummary($class);
-    }
-
     /**
      * Returns help information for this controller.
      *
@@ -322,23 +301,30 @@ class Controller extends \yii\base\Controller
     }
 
     /**
-     * Returns help information for this controller action.
+     * Returns a one-line short summary describing the specified action.
-     *
+     * @param \yii\base\Action $action action to get summary for
-     * You may override this method to return customized help.
+     * @return string a one-line short summary describing the specified action.
-     * 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)
+    public function getActionHelpSummary($action)
     {
-        $action = $this->createAction($actionID);
-
         if ($action instanceof InlineAction) {
-            $class = new \ReflectionMethod($this, $action->actionMethod);
+            return HelpParser::getSummary(new \ReflectionMethod($this, $action->actionMethod));
         } else {
-            $class = new \ReflectionClass($action);
+            return HelpParser::getSummary(new \ReflectionMethod($action, 'run'));
+        }
     }
 
-        return HelpParser::getDetail($class);
+    /**
+     * Returns the detailed help information for the specified action.
+     * @param \yii\base\Action $action action to get help for
+     * @return string the detailed help information for the specified action.
+     */
+    public function getActionHelp($action)
+    {
+        if ($action instanceof InlineAction) {
+            return HelpParser::getDetail(new \ReflectionMethod($this, $action->actionMethod));
+        } else {
+            return HelpParser::getDetail(new \ReflectionMethod($action, 'run'));
+        }
     }
 }

framework/console/controllers/HelpController.php

@@ -62,12 +62,12 @@ class HelpController extends Controller
 
             $actions = $this->getActions($controller);
             if ($actionID !== '' || count($actions) === 1 && $actions[0] === $controller->defaultAction) {
-                $this->getControllerActionHelp($controller, $actionID);
+                $this->getSubCommandHelp($controller, $actionID);
             } else {
-                $this->getControllerHelp($controller);
+                $this->getCommandHelp($controller);
             }
         } else {
-            $this->getGlobalHelp();
+            $this->getDefaultHelp();
         }
     }
 
@@ -182,7 +182,7 @@ class HelpController extends Controller
     /**
      * Displays all available commands.
      */
-    protected function getGlobalHelp()
+    protected function getDefaultHelp()
     {
         $commands = $this->getCommandDescriptions();
         if (!empty($commands)) {
@@ -211,7 +211,7 @@ class HelpController extends Controller
      * Displays the overall information of the command.
      * @param Controller $controller the controller instance
      */
-    protected function getControllerHelp($controller)
+    protected function getCommandHelp($controller)
     {
         $controller->color = $this->color;
 
@@ -230,7 +230,7 @@ class HelpController extends Controller
                 if ($action === $controller->defaultAction) {
                     $this->stdout(' (default)', Console::FG_GREEN);
                 }
-                $summary = $this->getActionSummary($controller, $action);
+                $summary = $controller->getActionHelpSummary($controller->createAction($action));
                 if ($summary !== '') {
                     echo ': ' . $summary;
                 }
@@ -243,33 +243,13 @@ class HelpController extends Controller
         }
     }
 
-    /**
-     * Returns the short summary of the action.
-     * @param Controller $controller the controller instance
-     * @param string $actionID action ID
-     * @return string the summary about the action
-     */
-    protected function getActionSummary($controller, $actionID)
-    {
-        $description = null;
-        $action = $controller->createAction($actionID);
-
-        if ($action instanceof Action) {
-            $description = $action->getHelpSummary();
-        }
-        if ($description === null) {
-            $description = $controller->getActionHelpSummary($actionID);
-        }
-        return $description;
-    }
-
     /**
      * Displays the detailed information of a command action.
      * @param Controller $controller the controller instance
      * @param string $actionID action ID
      * @throws Exception if the action does not exist
      */
-    protected function getControllerActionHelp($controller, $actionID)
+    protected function getSubCommandHelp($controller, $actionID)
     {
         $action = $controller->createAction($actionID);
         if ($action === null) {
@@ -277,22 +257,9 @@ class HelpController extends Controller
                 'command' => rtrim($controller->getUniqueId() . '/' . $actionID, '/'),
             ]));
         }
-        $description = null;
-        if ($action instanceof InlineAction) {
-            $method = new \ReflectionMethod($controller, $action->actionMethod);
-        } else {
-            /** @var Action $action */
-            $description = $action->getHelp();
-            $method = new \ReflectionMethod($action, 'run');
-        }
 
-        $tags = $this->parseComment($method->getDocComment());
+        $description = $controller->getActionHelp($action);
-        $options = $this->getOptionHelps($controller, $actionID);
+        if ($description != '') {
-
-        if ($description === null) {
-            $description = $controller->getActionHelp($actionID);
-        }
-        if ($description !== '') {
             $this->stdout("\nDESCRIPTION\n", Console::BOLD);
             $this->stdout("\n$description\n\n");
         }
@@ -304,6 +271,15 @@ class HelpController extends Controller
         } else {
             echo $scriptName . ' ' . $this->ansiFormat($action->getUniqueId(), Console::FG_YELLOW);
         }
+
+        if ($action instanceof InlineAction) {
+            $method = new \ReflectionMethod($controller, $action->actionMethod);
+        } else {
+            $method = new \ReflectionMethod($action, 'run');
+        }
+        $tags = $this->parseComment($method->getDocComment());
+        $options = $this->getOptionHelps($controller, $actionID);
+
         list ($required, $optional) = $this->getArgHelps($method, isset($tags['param']) ? $tags['param'] : []);
         foreach ($required as $arg => $description) {
             $this->stdout(' <' . $arg . '>', Console::FG_CYAN);

framework/helpers/BaseConsole.php

@@ -491,15 +491,15 @@ class BaseConsole
      * </pre>
      * First param is the string to convert, second is an optional flag if
      * colors should be used. It defaults to true, if set to false, the
-     * colorcodes will just be removed (And %% will be transformed into %)
+     * color codes will just be removed (And %% will be transformed into %)
      *
      * @param string $string String to convert
      * @param boolean $colored Should the string be colored?
      * @return string
      */
-    // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746
     public static function renderColoredString($string, $colored = true)
     {
+        // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746
         static $conversions = [
             '%y' => [self::FG_YELLOW],
             '%g' => [self::FG_GREEN],
@@ -562,9 +562,9 @@ class BaseConsole
      * @access public
      * @return string
      */
-    // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746
     public static function escape($string)
     {
+        // TODO rework/refactor according to https://github.com/yiisoft/yii2/issues/746
         return str_replace('%', '%%', $string);
     }