diff --git a/framework/console/Action.php b/framework/console/Action.php index 197495ef99..dbb3b35498 100644 --- a/framework/console/Action.php +++ b/framework/console/Action.php @@ -14,32 +14,33 @@ use yii\helpers\Console; * Action is the base class for all controller action classes. * * @inheritdoc + * @property \yii\console\Controller $controller * * @author Carsten Brandt * @since 2.0 */ class Action extends \yii\base\Action { + /** + * Returns a short description (one line) of information about the action. + * + * The default implementation returns help information retrieved from the PHPDoc comments. + * + * @return string + */ public function getDescription() { - $class = new \ReflectionClass($this); - $docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment()); - if (isset($docLines[1])) { - return trim($docLines[1], ' *'); - } - return ''; + return null; } + /** + * Returns help information for the action. + * + * The default implementation returns help information retrieved from the PHPDoc comments. + * @return string + */ public function getHelp() { - $class = new \ReflectionClass($this); - $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))); - } - return ''; + return null; } } diff --git a/framework/console/Controller.php b/framework/console/Controller.php index 92c16b8e92..d8b9221cb2 100644 --- a/framework/console/Controller.php +++ b/framework/console/Controller.php @@ -284,18 +284,30 @@ class Controller extends \yii\base\Controller } /** - * Returns a short description (one line) of information about this controller or an action. + * Returns a short description (one line) of information about this controller or it's action (if specified). * - * You may override this method to return customized help information for 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. * + * @param string $actionID action to get description for. null means overall controller description. * @return string */ - public function getDescription() + public function getDescription($actionID = null) { - $class = new \ReflectionClass($this); - $docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment()); + $action = null; + if ($actionID === null) { + $class = new \ReflectionClass($this); + } else { + $action = $this->createAction($actionID); + $class = new \ReflectionClass($action); + } + + if ($action instanceof InlineAction) { + $class = new \ReflectionMethod($this, $action->actionMethod); + } + + $docLines = preg_split('~\R~', $class->getDocComment()); if (isset($docLines[1])) { return trim($docLines[1], ' *'); } @@ -303,15 +315,27 @@ class Controller extends \yii\base\Controller } /** - * Returns help information for this controller. + * Returns help information for this controller or it's action (if specified). * + * 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. * @return string */ - public function getHelp() + public function getHelp($actionID = null) { - $class = new \ReflectionClass($this); + $action = null; + if ($actionID === null) { + $class = new \ReflectionClass($this); + } else { + $class = new \ReflectionClass($this->createAction($actionID)); + } + + if ($action instanceof InlineAction) { + $class = new \ReflectionMethod($this, $action->actionMethod); + } + $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])); diff --git a/framework/console/InlineAction.php b/framework/console/InlineAction.php index 264d5d5f04..1a3a330018 100644 --- a/framework/console/InlineAction.php +++ b/framework/console/InlineAction.php @@ -20,26 +20,27 @@ use yii\helpers\Console; */ class InlineAction extends \yii\base\InlineAction { + + /** + * Returns a short description (one line) of information about the action. + * + * The default implementation returns help information retrieved from the PHPDoc comments. + * + * @return string + */ public function getDescription() { - $class = new \ReflectionMethod($this->controller, $this->actionMethod); - $docLines = preg_split('~(\n|\r|\r\n)~', $class->getDocComment()); - if (isset($docLines[1])) { - return trim($docLines[1], ' *'); - } - return ''; + return null; } + /** + * Returns help information for the action. + * + * The default implementation returns help information retrieved from the PHPDoc comments. + * @return string + */ public function getHelp() { - $class = new \ReflectionMethod($this->controller, $this->actionMethod); - $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))); - } - return ''; + return null; } } diff --git a/framework/console/controllers/HelpController.php b/framework/console/controllers/HelpController.php index 1a5ba688a7..8cee1725bb 100644 --- a/framework/console/controllers/HelpController.php +++ b/framework/console/controllers/HelpController.php @@ -250,11 +250,15 @@ class HelpController extends Controller */ protected function getActionSummary($controller, $actionID) { + $description = ''; $action = $controller->createAction($actionID); if ($action instanceof InlineAction || $action instanceof Action) { - return $action->getDescription(); + $description = $action->getDescription(); + if ($description === null) { + $description = $controller->getDescription($actionID); + } } - return ''; + return $description; } /** @@ -281,6 +285,9 @@ class HelpController extends Controller $options = $this->getOptionHelps($controller, $actionID); $description = $action->getHelp(); + if ($description === null) { + $description = $controller->getHelp($actionID); + } if ($description !== '') { $this->stdout("\nDESCRIPTION\n", Console::BOLD); $this->stdout("\n$description\n\n");