phpdoc formatting issues

build/controllers/PhpDocController.php

@@ -205,16 +205,18 @@ protected function fixDocBlockIndentation(&$lines)
         $listIndent = false;
         $indent = '';
         foreach($lines as $i => $line) {
-            if (preg_match('~^(\s+)/\*\*$~', $line, $matches)) {
+            if (preg_match('~^(\s*)/\*\*$~', $line, $matches)) {
                 $docBlock = true;
                 $indent = $matches[1];
-            } elseif (preg_match('~^(\s+)\*/~', $line)) {
+            } elseif (preg_match('~^(\s+)\*+/~', $line)) {
+                if ($docBlock) { // could be the end of normal comment
+                    $lines[$i] = $indent . ' */';
+                }
                 $docBlock = false;
                 $codeBlock = false;
                 $listIndent = '';
-                $lines[$i] = $indent . ' */';
             } elseif ($docBlock) {
-                $docLine = trim($line, " \t*");
+                $docLine = str_replace("\t", '    ', rtrim(substr(ltrim($line), 2)));
                 if (empty($docLine)) {
                     $listIndent = '';
                 } elseif ($docLine[0] === '@') {
@@ -223,15 +225,16 @@ protected function fixDocBlockIndentation(&$lines)
                     $docLine = preg_replace('/\s+/', ' ', $docLine);
                 } elseif (preg_match('/^(~~~|```)/', $docLine)) {
                     $codeBlock = !$codeBlock;
-                } elseif (preg_match('/^([0-9]+\.|-|\*|\+) /', $docLine, $matches)) {
+                    $listIndent = '';
+                } elseif (preg_match('/^(\s*)([0-9]+\.|-|\*|\+) /', $docLine, $matches)) {
                     $listIndent = str_repeat(' ', strlen($matches[0]));
                     $lines[$i] = $indent . ' * ' . $docLine;
                     continue;
                 }
                 if ($codeBlock) {
-                    $lines[$i] = rtrim($indent . ' * ' . substr(ltrim($line), 2));
+                    $lines[$i] = rtrim($indent . ' * ' . $docLine);
                 } else {
-                    $lines[$i] = rtrim($indent . ' * ' . $listIndent . $docLine);
+                    $lines[$i] = rtrim($indent . ' * ' . (empty($listIndent) ? $docLine : ($listIndent . ltrim($docLine))));
                 }
             }
         }

framework/BaseYii.php

@@ -4,6 +4,7 @@
  * @copyright Copyright (c) 2008 Yii Software LLC
  * @license http://www.yiiframework.com/license/
  */
+
 namespace yii;
 
 use yii\base\InvalidConfigException;

framework/base/Action.php

@@ -32,7 +32,7 @@
  * read-only.
  *
  * @author Qiang Xue <[email protected]>
- * @since  2.0
+ * @since 2.0
  */
 class Action extends Component
 {

framework/base/Behavior.php

@@ -46,8 +46,8 @@ class Behavior extends \yii\base\Object
      *
      * ~~~
      * [
-     *	 Model::EVENT_BEFORE_VALIDATE => 'myBeforeValidate',
-     *	 Model::EVENT_AFTER_VALIDATE => 'myAfterValidate',
+     *  Model::EVENT_BEFORE_VALIDATE => 'myBeforeValidate',
+     *  Model::EVENT_AFTER_VALIDATE => 'myAfterValidate',
      * ]
      * ~~~
      *

framework/base/InlineAction.php

@@ -21,14 +21,14 @@
 class InlineAction extends Action
 {
     /**
-     * @var string the controller method that  this inline action is associated with
+     * @var string the controller method that this inline action is associated with
      */
     public $actionMethod;
 
     /**
      * @param string $id the ID of this action
      * @param Controller $controller the controller that owns this action
-     * @param string $actionMethod the controller method that  this inline action is associated with
+     * @param string $actionMethod the controller method that this inline action is associated with
      * @param array $config name-value pairs that will be used to initialize the object properties
      */
     public function __construct($id, $controller, $actionMethod, $config = [])

framework/base/Module.php

@@ -263,8 +263,8 @@ public function setLayoutPath($path)
      *
      * ~~~
      * [
-     *	'@models' => '@app/models', // an existing alias
-     *	'@backend' => __DIR__ . '/../backend',  // a directory
+     *     '@models' => '@app/models', // an existing alias
+     *     '@backend' => __DIR__ . '/../backend',  // a directory
      * ]
      * ~~~
      */

framework/base/Widget.php

@@ -171,7 +171,7 @@ public function run()
      * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
      *
      * If the view name does not contain a file extension, it will use the default one `.php`.
-
+     *
      * @param string $view the view name.
      * @param array $params the parameters (name-value pairs) that should be made available in the view.
      * @return string the rendering result.

framework/caching/DbCache.php

@@ -69,7 +69,7 @@ class DbCache extends Cache
      * @var integer the probability (parts per million) that garbage collection (GC) should be performed
      * when storing a piece of data in the cache. Defaults to 100, meaning 0.01% chance.
      * This number should be between 0 and 1000000. A value 0 meaning no GC will be performed at all.
-     **/
+     */
     public $gcProbability = 100;
 
     /**

framework/caching/FileCache.php

@@ -52,7 +52,7 @@ class FileCache extends Cache
      * @var integer the probability (parts per million) that garbage collection (GC) should be performed
      * when storing a piece of data in the cache. Defaults to 10, meaning 0.001% chance.
      * This number should be between 0 and 1000000. A value 0 means no GC will be performed at all.
-     **/
+     */
     public $gcProbability = 10;
     /**
      * @var integer the permission to be set for newly created cache files.

framework/captcha/CaptchaAction.php

@@ -82,7 +82,7 @@ class CaptchaAction extends Action
     /**
      * @var integer the offset between characters. Defaults to -2. You can adjust this property
      * in order to decrease or increase the readability of the captcha.
-     **/
+     */
     public $offset = -2;
     /**
      * @var string the TrueType font file. This can be either a file path or path alias.

framework/db/Connection.php

@@ -76,17 +76,15 @@
  * configuration like the following:
  *
  * ~~~
- * [
- *	 'components' => [
- *		 'db' => [
- *			 'class' => '\yii\db\Connection',
- *			 'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
- *			 'username' => 'root',
- *			 'password' => '',
- *			 'charset' => 'utf8',
- *		 ],
- *	 ],
- * ]
+ * 'components' => [
+ *     'db' => [
+ *         'class' => '\yii\db\Connection',
+ *         'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
+ *         'username' => 'root',
+ *         'password' => '',
+ *         'charset' => 'utf8',
+ *     ],
+ * ],
  * ~~~
  *
  * @property string $driverName Name of the DB driver.

framework/db/Query.php

@@ -486,50 +486,50 @@ public function from($tables)
      * can be one of the followings:
      *
      * - `and`: the operands should be concatenated together using `AND`. For example,
-     * `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
-     * it will be converted into a string using the rules described here. For example,
-     * `['and', 'type=1', ['or', 'id=1', 'id=2']]` will generate `type=1 AND (id=1 OR id=2)`.
-     * The method will NOT do any quoting or escaping.
+     *   `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
+     *   it will be converted into a string using the rules described here. For example,
+     *   `['and', 'type=1', ['or', 'id=1', 'id=2']]` will generate `type=1 AND (id=1 OR id=2)`.
+     *   The method will NOT do any quoting or escaping.
      *
      * - `or`: similar to the `and` operator except that the operands are concatenated using `OR`.
      *
      * - `between`: operand 1 should be the column name, and operand 2 and 3 should be the
-     * starting and ending values of the range that the column is in.
-     * For example, `['between', 'id', 1, 10]` will generate `id BETWEEN 1 AND 10`.
+     *   starting and ending values of the range that the column is in.
+     *   For example, `['between', 'id', 1, 10]` will generate `id BETWEEN 1 AND 10`.
      *
      * - `not between`: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
-     * in the generated condition.
+     *   in the generated condition.
      *
      * - `in`: operand 1 should be a column or DB expression with parenthesis. Operand 2 can be an array
-     * or a Query object. If the former, the array represents the range of the values that the column
-     * or DB expression should be in. If the latter, a sub-query will be generated to represent the range.
-     * For example, `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`;
-     * `['in', 'id', (new Query)->select('id')->from('user'))]` will generate
-     * `id IN (SELECT id FROM user)`. The method will properly quote the column name and escape values in the range.
+     *   or a Query object. If the former, the array represents the range of the values that the column
+     *   or DB expression should be in. If the latter, a sub-query will be generated to represent the range.
+     *   For example, `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`;
+     *   `['in', 'id', (new Query)->select('id')->from('user'))]` will generate
+     *   `id IN (SELECT id FROM user)`. The method will properly quote the column name and escape values in the range.
      *
      * - `not in`: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
      *
      * - `like`: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing
-     * the values that the column or DB expression should be like.
-     * For example, `['like', 'name', 'tester']` will generate `name LIKE '%tester%'`.
-     * When the value range is given as an array, multiple `LIKE` predicates will be generated and concatenated
-     * using `AND`. For example, `['like', 'name', ['test', 'sample']]` will generate
-     * `name LIKE '%test%' AND name LIKE '%sample%'`.
-     * The method will properly quote the column name and escape special characters in the values.
-     * Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply
-     * a third operand `false` to do so. For example, `['like', 'name', '%tester', false]` will generate `name LIKE '%tester'`.
+     *   the values that the column or DB expression should be like.
+     *   For example, `['like', 'name', 'tester']` will generate `name LIKE '%tester%'`.
+     *   When the value range is given as an array, multiple `LIKE` predicates will be generated and concatenated
+     *   using `AND`. For example, `['like', 'name', ['test', 'sample']]` will generate
+     *   `name LIKE '%test%' AND name LIKE '%sample%'`.
+     *   The method will properly quote the column name and escape special characters in the values.
+     *   Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply
+     *   a third operand `false` to do so. For example, `['like', 'name', '%tester', false]` will generate `name LIKE '%tester'`.
      *
      * - `or like`: similar to the `like` operator except that `OR` is used to concatenate the `LIKE`
-     * predicates when operand 2 is an array.
+     *   predicates when operand 2 is an array.
      *
      * - `not like`: similar to the `like` operator except that `LIKE` is replaced with `NOT LIKE`
-     * in the generated condition.
+     *   in the generated condition.
      *
      * - `or not like`: similar to the `not like` operator except that `OR` is used to concatenate
-     * the `NOT LIKE` predicates.
+     *   the `NOT LIKE` predicates.
      *
      * - `exists`: requires one operand which must be an instance of [[Query]] representing the sub-query.
-     * It will build a `EXISTS (sub-query)` expression.
+     *   It will build a `EXISTS (sub-query)` expression.
      *
      * - `not exists`: similar to the `exists` operator and builds a `NOT EXISTS (sub-query)` expression.
      *

framework/db/QueryBuilder.php

@@ -95,8 +95,8 @@ public function build($query, $params = [])
      *
      * ~~~
      * $sql = $queryBuilder->insert('user', [
-     *	 'name' => 'Sam',
-     *	 'age' => 30,
+     *  'name' => 'Sam',
+     *  'age' => 30,
      * ], $params);
      * ~~~
      *
@@ -277,9 +277,9 @@ public function delete($table, $condition, &$params)
      *
      * ~~~
      * $sql = $queryBuilder->createTable('user', [
-     *	 'id' => 'pk',
-     *	 'name' => 'string',
-     *	 'age' => 'integer',
+     *  'id' => 'pk',
+     *  'name' => 'string',
+     *  'age' => 'integer',
      * ]);
      * ~~~
      *
@@ -350,7 +350,7 @@ public function addPrimaryKey($name, $table, $columns)
      * Builds a SQL statement for removing a primary key constraint to an existing table.
      * @param string $name the name of the primary key constraint to be removed.
      * @param string $table the table that the primary key constraint will be removed from.
-     * @return string the SQL statement for removing a primary key constraint from an existing table.	 *
+     * @return string the SQL statement for removing a primary key constraint from an existing table.
      */
     public function dropPrimaryKey($name, $table)
     {

framework/db/QueryInterface.php

@@ -96,45 +96,45 @@ public function indexBy($column);
      * can be one of the followings:
      *
      * - `and`: the operands should be concatenated together using `AND`. For example,
-     * `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
-     * it will be converted into a string using the rules described here. For example,
-     * `['and', 'type=1', ['or', 'id=1', 'id=2']]` will generate `type=1 AND (id=1 OR id=2)`.
-     * The method will NOT do any quoting or escaping.
+     *   `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
+     *   it will be converted into a string using the rules described here. For example,
+     *   `['and', 'type=1', ['or', 'id=1', 'id=2']]` will generate `type=1 AND (id=1 OR id=2)`.
+     *   The method will NOT do any quoting or escaping.
      *
      * - `or`: similar to the `and` operator except that the operands are concatenated using `OR`.
      *
      * - `between`: operand 1 should be the column name, and operand 2 and 3 should be the
-     * starting and ending values of the range that the column is in.
-     * For example, `['between', 'id', 1, 10]` will generate `id BETWEEN 1 AND 10`.
+     *   starting and ending values of the range that the column is in.
+     *   For example, `['between', 'id', 1, 10]` will generate `id BETWEEN 1 AND 10`.
      *
      * - `not between`: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
-     * in the generated condition.
+     *   in the generated condition.
      *
      * - `in`: operand 1 should be a column or DB expression, and operand 2 be an array representing
-     * the range of the values that the column or DB expression should be in. For example,
-     * `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`.
-     * The method will properly quote the column name and escape values in the range.
+     *   the range of the values that the column or DB expression should be in. For example,
+     *   `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`.
+     *   The method will properly quote the column name and escape values in the range.
      *
      * - `not in`: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
      *
      * - `like`: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing
-     * the values that the column or DB expression should be like.
-     * For example, `['like', 'name', 'tester']` will generate `name LIKE '%tester%'`.
-     * When the value range is given as an array, multiple `LIKE` predicates will be generated and concatenated
-     * using `AND`. For example, `['like', 'name', ['test', 'sample']]` will generate
-     * `name LIKE '%test%' AND name LIKE '%sample%'`.
-     * The method will properly quote the column name and escape special characters in the values.
-     * Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply
-     * a third operand `false` to do so. For example, `['like', 'name', '%tester', false]` will generate `name LIKE '%tester'`.
+     *   the values that the column or DB expression should be like.
+     *   For example, `['like', 'name', 'tester']` will generate `name LIKE '%tester%'`.
+     *   When the value range is given as an array, multiple `LIKE` predicates will be generated and concatenated
+     *   using `AND`. For example, `['like', 'name', ['test', 'sample']]` will generate
+     *   `name LIKE '%test%' AND name LIKE '%sample%'`.
+     *   The method will properly quote the column name and escape special characters in the values.
+     *   Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply
+     *   a third operand `false` to do so. For example, `['like', 'name', '%tester', false]` will generate `name LIKE '%tester'`.
      *
      * - `or like`: similar to the `like` operator except that `OR` is used to concatenate the `LIKE`
-     * predicates when operand 2 is an array.
+     *   predicates when operand 2 is an array.
      *
      * - `not like`: similar to the `like` operator except that `LIKE` is replaced with `NOT LIKE`
-     * in the generated condition.
+     *   in the generated condition.
      *
      * - `or not like`: similar to the `not like` operator except that `OR` is used to concatenate
-     * the `NOT LIKE` predicates.
+     *   the `NOT LIKE` predicates.
      *
      * @param string|array $condition the conditions that should be put in the WHERE part.
      * @return static the query object itself

framework/db/Schema.php

@@ -264,8 +264,8 @@ protected function findTableNames($schema = '')
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/db/TableSchema.php

@@ -47,9 +47,9 @@ class TableSchema extends Object
      *
      * ~~~
      * [
-     *	 'ForeignTableName',
-     *	 'fk1' => 'pk1',  // pk1 is in foreign table
-     *	 'fk2' => 'pk2',  // if composite foreign key
+     *  'ForeignTableName',
+     *  'fk1' => 'pk1',  // pk1 is in foreign table
+     *  'fk2' => 'pk2',  // if composite foreign key
      * ]
      * ~~~
      */

framework/db/mysql/Schema.php

@@ -254,8 +254,8 @@ protected function findConstraints($table)
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/db/pgsql/Schema.php

@@ -265,8 +265,8 @@ protected function getUniqueIndexInformation($table)
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/db/sqlite/QueryBuilder.php

@@ -254,7 +254,7 @@ public function addPrimaryKey($name, $table, $columns)
      * @param string $name the name of the primary key constraint to be removed.
      * @param string $table the table that the primary key constraint will be removed from.
      * @return string the SQL statement for removing a primary key constraint from an existing table.
-     * @throws NotSupportedException this is not supported by SQLite	 *
+     * @throws NotSupportedException this is not supported by SQLite
      */
     public function dropPrimaryKey($name, $table)
     {