Skip to content

Y
yii2
Commit 91c16782 by Carsten Brandt
Options

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
parent 1d622b65
Showing with 59 additions and 26 deletions
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 <mail@cebe.cc>
* @author Alexander Makarov <sam@rmcreative.ru>
* @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 (?<type>[\w\\|\\\\\\[\\]]+) \$\w+(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
'[\s\n]{2,}public function (?<kind>set)(?<name>\w+)\(\$\w+(?:, ?\$\w+ ?= ?[^,]+)*\)#',
$class['content']);
$acrs = array_merge($gets, $sets);
// check for @property annotations in getter and setter
$properties = $this->match(
'#\* @(?<kind>property) (?<type>[\w\\|\\\\\\[\\]]+)(?: (?<comment>(?:(?!\*/|\* @).)+?)(?:(?!\*/).)+|[\s\n]*)\*/' .
'[\s\n]{2,}public function [g|s]et(?<name>\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
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 <qiang.xue@gmail.com>
* @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:
*
......
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 <qiang.xue@gmail.com>
* @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,
......
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 <qiang.xue@gmail.com>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment