From 91c16782ef3359c7e73cd27d767a1842c9f8b915 Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Wed, 28 Aug 2013 18:58:59 +0200 Subject: [PATCH] finalized PhpDocController - cleanup API and usage, add documetation link - introduced @property feature in getter or setter which has precedence over @return or @param tag if present --- build/controllers/PhpDocController.php | 43 +++++++++++++++++++++++++--------- framework/yii/base/Model.php | 16 +++++++++---- framework/yii/base/Module.php | 23 ++++++++++-------- framework/yii/data/DataProvider.php | 2 +- 4 files changed, 58 insertions(+), 26 deletions(-) diff --git a/build/controllers/PhpDocController.php b/build/controllers/PhpDocController.php index 1011d19..5aac7e5 100644 --- a/build/controllers/PhpDocController.php +++ b/build/controllers/PhpDocController.php @@ -13,19 +13,32 @@ use yii\helpers\FileHelper; /** * PhpDocController is there to help maintaining PHPDoc annotation in class files + * * @author Carsten Brandt * @author Alexander Makarov * @since 2.0 */ class PhpDocController extends Controller { + public $defaultAction = 'property'; + + /** + * @var bool whether to update class docs directly. Setting this to false will just output docs + * for copy and paste. + */ + public $updateFiles = true; + /** * Generates @property annotations in class files from getters and setters * - * @param null $root the directory to parse files from - * @param bool $updateFiles whether to update class docs directly + * Property description will be taken from getter or setter or from an @property annotation + * in the getters docblock if there is one defined. + * + * See https://github.com/yiisoft/yii2/wiki/Core-framework-code-style#documentation for details. + * + * @param null $root the directory to parse files from. Defaults to YII_PATH. */ - public function actionProperty($root=null, $updateFiles=true) + public function actionProperty($root=null) { if ($root === null) { $root = YII_PATH; @@ -58,7 +71,7 @@ class PhpDocController extends Controller $result = $this->generateClassPropertyDocs($file); if ($result !== false) { list($className, $phpdoc) = $result; - if ($updateFiles) { + if ($this->updateFiles) { if ($this->updateClassPropertyDocs($file, $className, $phpdoc)) { $nFilesUpdated++; } @@ -70,10 +83,15 @@ class PhpDocController extends Controller $nFilesTotal++; } - $this->stdout("\n\nParsed $nFilesTotal files.\n"); + $this->stdout("\nParsed $nFilesTotal files.\n"); $this->stdout("Updated $nFilesUpdated files.\n"); } + public function globalOptions() + { + return array_merge(parent::globalOptions(), array('updateFiles')); + } + protected function updateClassPropertyDocs($file, $className, $propertyDoc) { $ref = new \ReflectionClass($className); @@ -229,7 +247,12 @@ class PhpDocController extends Controller '#\* @param (?[\w\\|\\\\\\[\\]]+) \$\w+(?: (?(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' . '[\s\n]{2,}public function (?set)(?\w+)\(\$\w+(?:, ?\$\w+ ?= ?[^,]+)*\)#', $class['content']); - $acrs = array_merge($gets, $sets); + // check for @property annotations in getter and setter + $properties = $this->match( + '#\* @(?property) (?[\w\\|\\\\\\[\\]]+)(?: (?(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' . + '[\s\n]{2,}public function [g|s]et(?\w+)\(((?:,? ?\$\w+ ?= ?[^,]+)*|\$\w+(?:, ?\$\w+ ?= ?[^,]+)*)\)#', + $class['content']); + $acrs = array_merge($properties, $gets, $sets); //print_r($acrs); continue; $props = array(); @@ -244,10 +267,6 @@ class PhpDocController extends Controller ksort($props); -// foreach ($props as $propName => &$prop) // I don't like write-only props... -// if (!isset($prop['get'])) -// unset($props[$propName]); - if (count($props) > 0) { $phpdoc .= " *\n"; foreach ($props as $propName => &$prop) { @@ -265,6 +284,8 @@ class PhpDocController extends Controller } elseif (isset($prop['set'])) { $note = ' This property is write-only.'; // $docline .= '-write'; + } else { + continue; } $docline .= ' ' . $this->getPropParam($prop, 'type') . " $$propName "; $comment = explode("\n", $this->getPropParam($prop, 'comment') . $note); @@ -302,6 +323,6 @@ class PhpDocController extends Controller protected function getPropParam($prop, $param) { - return isset($prop['get']) ? $prop['get'][$param] : $prop['set'][$param]; + return isset($prop['property']) ? $prop['property'][$param] : (isset($prop['get']) ? $prop['get'][$param] : $prop['set'][$param]); } } \ No newline at end of file diff --git a/framework/yii/base/Model.php b/framework/yii/base/Model.php index aca3e0b..a195acd 100644 --- a/framework/yii/base/Model.php +++ b/framework/yii/base/Model.php @@ -36,11 +36,17 @@ use yii\validators\Validator; * You may directly use Model to store model data, or extend it with customization. * You may also customize Model by attaching [[ModelBehavior|model behaviors]]. * - * @property ArrayObject $validators All the validators declared in the model. - * @property array $activeValidators The validators applicable to the current [[scenario]]. - * @property array $errors Errors for all attributes or the specified attribute. Empty array is returned if no error. + * @property \yii\validators\Validator[] $activeValidators The validators applicable to the current + * [[scenario]]. This property is read-only. * @property array $attributes Attribute values (name => value). - * @property string $scenario The scenario that this model is in. + * @property array $errors An array of errors for all attributes. Empty array is returned if no error. The + * result is a two-dimensional array. See [[getErrors()]] for detailed description. This property is read-only. + * @property array $firstErrors The first errors. An empty array will be returned if there is no error. This + * property is read-only. + * @property ArrayIterator $iterator An iterator for traversing the items in the list. This property is + * read-only. + * @property string $scenario The scenario that this model is in. Defaults to 'default'. + * @property ArrayObject $validators All the validators declared in the model. This property is read-only. * * @author Qiang Xue * @since 2.0 @@ -423,6 +429,8 @@ class Model extends Component implements IteratorAggregate, ArrayAccess /** * Returns the errors for all attribute or a single attribute. * @param string $attribute attribute name. Use null to retrieve errors for all attributes. + * @property array An array of errors for all attributes. Empty array is returned if no error. + * The result is a two-dimensional array. See [[getErrors()]] for detailed description. * @return array errors for all attributes or the specified attribute. Empty array is returned if no error. * Note that when returning errors for all attributes, the result is a two-dimensional array, like the following: * diff --git a/framework/yii/base/Module.php b/framework/yii/base/Module.php index a85385b..1b7bf5b 100644 --- a/framework/yii/base/Module.php +++ b/framework/yii/base/Module.php @@ -20,16 +20,16 @@ use Yii; * [[components|Components]] may be registered with the module so that they are globally * accessible within the module. * - * @property string $uniqueId An ID that uniquely identifies this module among all modules within - * the current application. - * @property string $basePath The root directory of the module. Defaults to the directory containing the module class. - * @property string $controllerPath The directory containing the controller classes. Defaults to "[[basePath]]/controllers". - * @property string $viewPath The directory containing the view files within this module. Defaults to "[[basePath]]/views". - * @property string $layoutPath The directory containing the layout view files within this module. Defaults to "[[viewPath]]/layouts". - * @property array $modules The configuration of the currently installed modules (module ID => configuration). - * @property array $components The components (indexed by their IDs) registered within this module. - * @property array $import List of aliases to be imported. This property is write-only. - * @property array $aliases List of aliases to be defined. This property is write-only. + * @property array $aliases List of path aliases to be defined. The array keys are alias names (must start + * with '@') and the array values are the corresponding paths or aliases. See [[setAliases()]] for an example. + * This property is write-only. + * @property string $basePath The root directory of the module. + * @property array $components The components (indexed by their IDs). + * @property string $controllerPath The directory that contains the controller classes. + * @property string $layoutPath The root directory of layout files. Defaults to "[[viewPath]]/layouts". + * @property array $modules The modules (indexed by their IDs). + * @property string $uniqueId The unique ID of the module. This property is read-only. + * @property string $viewPath The root directory of view files. Defaults to "[[basePath]]/view". * * @author Qiang Xue * @since 2.0 @@ -304,6 +304,9 @@ abstract class Module extends Component * Defines path aliases. * This method calls [[Yii::setAlias()]] to register the path aliases. * This method is provided so that you can define path aliases when configuring a module. + * @property array list of path aliases to be defined. The array keys are alias names + * (must start with '@') and the array values are the corresponding paths or aliases. + * See [[setAliases()]] for an example. * @param array $aliases list of path aliases to be defined. The array keys are alias names * (must start with '@') and the array values are the corresponding paths or aliases. * For example, diff --git a/framework/yii/data/DataProvider.php b/framework/yii/data/DataProvider.php index 7d0244c..84491d6 100644 --- a/framework/yii/data/DataProvider.php +++ b/framework/yii/data/DataProvider.php @@ -20,7 +20,7 @@ use yii\base\InvalidParamException; * @property Pagination|boolean $pagination The pagination object. If this is false, it means the pagination * is disabled. Note that the type of this property differs in getter and setter. See [[getPagination()]] and * [[setPagination()]] for details. - * @property Sort|boolean $sort The sorting object. If this is false, it means that sorting is disabled. Note + * @property Sort|boolean $sort The sorting object. If this is false, it means the sorting is disabled. Note * that the type of this property differs in getter and setter. See [[getSort()]] and [[setSort()]] for details. * * @author Qiang Xue