phpdoc formatting issues

build/controllers/PhpDocController.php

@@ -205,16 +205,18 @@ class PhpDocController extends Controller
         $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 @@ class PhpDocController extends Controller
                     $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 @@ use Yii;
  * read-only.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
- * @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 @@ use Yii;
 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 @@ class Module extends ServiceLocator
      *
      * ~~~
      * [
-     *	'@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 @@ class Widget extends Component implements ViewContextInterface
      * - 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 @@ use yii\caching\Cache;
  * 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 @@ class Query extends Component implements QueryInterface
      * 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 @@ class QueryBuilder extends \yii\base\Object
      *
      * ~~~
      * $sql = $queryBuilder->insert('user', [
-     *	 'name' => 'Sam',
-     *	 'age' => 30,
+     *  'name' => 'Sam',
+     *  'age' => 30,
      * ], $params);
      * ~~~
      *
@@ -277,9 +277,9 @@ class QueryBuilder extends \yii\base\Object
      *
      * ~~~
      * $sql = $queryBuilder->createTable('user', [
-     *	 'id' => 'pk',
-     *	 'name' => 'string',
-     *	 'age' => 'integer',
+     *  'id' => 'pk',
+     *  'name' => 'string',
+     *  'age' => 'integer',
      * ]);
      * ~~~
      *
@@ -350,7 +350,7 @@ class QueryBuilder extends \yii\base\Object
      * 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 @@ interface QueryInterface
      * 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 @@ abstract class Schema extends Object
      *
      * ~~~
      * [
-     *	 '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 @@ class Schema extends \yii\db\Schema
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/db/pgsql/Schema.php

@@ -265,8 +265,8 @@ SQL;
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/db/sqlite/QueryBuilder.php

@@ -254,7 +254,7 @@ class QueryBuilder extends \yii\db\QueryBuilder
      * @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)
     {

framework/db/sqlite/Schema.php

@@ -168,8 +168,8 @@ class Schema extends \yii\db\Schema
      *
      * ~~~
      * [
-     *	 'IndexName1' => ['col1' [, ...]],
-     *	 'IndexName2' => ['col2' [, ...]],
+     *  'IndexName1' => ['col1' [, ...]],
+     *  'IndexName2' => ['col2' [, ...]],
      * ]
      * ~~~
      *

framework/helpers/BaseSecurity.php

@@ -91,10 +91,10 @@ class BaseSecurity
     }
 
     /**
-    * Adds a padding to the given data (PKCS #7).
-    * @param string $data the data to pad
-    * @return string the padded data
-    */
+     * Adds a padding to the given data (PKCS #7).
+     * @param string $data the data to pad
+     * @return string the padded data
+     */
     protected static function addPadding($data)
     {
         $pad = self::CRYPT_BLOCK_SIZE - (StringHelper::byteLength($data) % self::CRYPT_BLOCK_SIZE);
@@ -103,10 +103,10 @@ class BaseSecurity
     }
 
     /**
-    * Strips the padding from the given data.
-    * @param string $data the data to trim
-    * @return string the trimmed data
-    */
+     * Strips the padding from the given data.
+     * @param string $data the data to trim
+     * @return string the trimmed data
+     */
     protected static function stripPadding($data)
     {
         $end = StringHelper::byteSubstr($data, -1, null);
@@ -120,11 +120,11 @@ class BaseSecurity
     }
 
     /**
-    * Derives a key from the given password (PBKDF2).
-    * @param string $password the source password
-    * @param string $salt the random salt
-    * @return string the derived key
-    */
+     * Derives a key from the given password (PBKDF2).
+     * @param string $password the source password
+     * @param string $salt the random salt
+     * @return string the derived key
+     */
     protected static function deriveKey($password, $salt)
     {
         if (function_exists('hash_pbkdf2')) {

framework/i18n/Formatter.php

@@ -305,7 +305,7 @@ class Formatter extends \yii\base\Formatter
     /**
      * Creates a number formatter based on the given type and format.
      * @param integer $type the type of the number formatter
-     * @param string $format the format to be used.  Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
+     * @param string $format the format to be used. Please refer to [ICU manual](http://www.icu-project.org/apiref/icu4c/classDecimalFormat.html#_details)
      * @return NumberFormatter the created formatter instance
      */
     protected function createNumberFormatter($type, $format)

framework/log/DbTarget.php

@@ -35,11 +35,11 @@ class DbTarget extends Target
      *
      * ~~~
      * CREATE TABLE log (
-     *	   id       BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
-     *	   level    INTEGER,
-     *	   category VARCHAR(255),
-     *	   log_time INTEGER,
-     *	   message  TEXT,
+     *     id       BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
+     *     level    INTEGER,
+     *     category VARCHAR(255),
+     *     log_time INTEGER,
+     *     message  TEXT,
      *     INDEX idx_log_level (level),
      *     INDEX idx_log_category (category)
      * )

framework/validators/RangeValidator.php

@@ -33,7 +33,7 @@ class RangeValidator extends Validator
     /**
      * @var boolean whether to invert the validation logic. Defaults to false. If set to true,
      * the attribute value should NOT be among the list of values defined via [[range]].
-     **/
+     */
     public $not = false;
 
     /**

framework/validators/RegularExpressionValidator.php

@@ -29,7 +29,7 @@ class RegularExpressionValidator extends Validator
     /**
      * @var boolean whether to invert the validation logic. Defaults to false. If set to true,
      * the regular expression defined via [[pattern]] should NOT match the attribute value.
-     **/
+     */
     public $not = false;
 
     /**

framework/validators/UrlValidator.php

@@ -32,13 +32,13 @@ class UrlValidator extends Validator
     /**
      * @var array list of URI schemes which should be considered valid. By default, http and https
      * are considered to be valid schemes.
-     **/
+     */
     public $validSchemes = ['http', 'https'];
     /**
      * @var string the default URI scheme. If the input doesn't contain the scheme part, the default
      * scheme will be prepended to it (thus changing the input). Defaults to null, meaning a URL must
      * contain the scheme part.
-     **/
+     */
     public $defaultScheme;
     /**
      * @var boolean whether validation process should take into account IDN (internationalized

framework/web/AssetManager.php

@@ -207,7 +207,7 @@ class AssetManager extends Component
      * discussion: http://code.google.com/p/yii/issues/detail?id=2579
      *
      * @param string $path the asset (file or directory) to be published
-     * @param array $options the options to	be applied when publishing a directory.
+     * @param array $options the options to be applied when publishing a directory.
      * The following options are supported:
      *
      * - beforeCopy: callback, a PHP callback that is called before copying each sub-directory or file.