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

@@ -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]);
 	}
 }

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>