added missing documentation about the NOT operator in Query

extensions/apidoc/models/Context.php

@@ -175,8 +175,11 @@ class Context extends Component
                     continue;
                 }
                 foreach (['shortDescription', 'description', 'return', 'returnType', 'returnTypes', 'exceptions'] as $property) {
+                    // set all properties that are empty. descriptions will be concatenated.
                     if (empty($m->$property) || is_string($m->$property) && trim($m->$property) === '') {
                         $m->$property = $inheritedMethod->$property;
+                    } elseif ($property == 'description') {
+                        $m->$property = rtrim($m->$property) . "\n\n" . ltrim($inheritedMethod->$property);
                     }
                 }
                 foreach ($m->params as $i => $param) {
@@ -194,7 +197,7 @@ class Context extends Component
                     if (empty($param->type) || trim($param->type) === '') {
                         $param->type = $inheritedMethod->params[$i]->type;
                     }
-                    if (empty($param->types) || trim($param->types) === '') {
+                    if (empty($param->types)) {
                         $param->types = $inheritedMethod->params[$i]->types;
                     }
                 }

extensions/elasticsearch/ActiveQuery.php

@@ -194,7 +194,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
             return null;
         }
         if ($this->asArray) {
-            // TODO implement with
+            // TODO implement with()
 //            /* @var $modelClass ActiveRecord */
 //            $modelClass = $this->modelClass;
 //            $model = $result['_source'];
@@ -230,7 +230,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
     public function search($db = null, $options = [])
     {
         $result = $this->createCommand($db)->search($options);
-        // TODO implement with for asArray
+        // TODO implement with() for asArray
         if (!empty($result['hits']['hits']) && !$this->asArray) {
             $models = $this->createModels($result['hits']['hits']);
             if (!empty($this->with)) {

framework/db/ActiveRelationTrait.php

@@ -17,8 +17,8 @@ use yii\base\InvalidParamException;
  * @author Carsten Brandt <mail@cebe.cc>
  * @since 2.0
  *
- * @method ActiveRelationTrait one()
- * @method ActiveRelationTrait[] all()
+ * @method ActiveRecordInterface one()
+ * @method ActiveRecordInterface[] all()
  * @property ActiveRecord $modelClass
  */
 trait ActiveRelationTrait

framework/db/Query.php

@@ -66,6 +66,12 @@ class Query extends Component implements QueryInterface
      */
     public $from;
     /**
+     * @var string|array query condition. This refers to the WHERE clause in a SQL statement.
+     * For example, `age > 31 AND team = 1`.
+     * @see where()
+     */
+    public $where;
+    /**
      * @var array how to group the query results. For example, `['company', 'department']`.
      * This is used to construct the GROUP BY clause in a SQL statement.
      */
@@ -465,81 +471,19 @@ class Query extends Component implements QueryInterface
     /**
      * Sets the WHERE part of the query.
      *
-     * The method requires a $condition parameter, and optionally a $params parameter
+     * The method requires a `$condition` parameter, and optionally a `$params` parameter
      * specifying the values to be bound to the query.
      *
-     * The $condition parameter should be either a string (e.g. 'id=1') or an array.
-     * If the latter, it must be in one of the following two formats:
-     *
-     * - hash format: `['column1' => value1, 'column2' => value2, ...]`
-     * - operator format: `[operator, operand1, operand2, ...]`
-     *
-     * A condition in hash format represents the following SQL expression in general:
-     * `column1=value1 AND column2=value2 AND ...`. In case when a value is an array or a Query object,
-     * an `IN` expression will be generated. And if a value is null, `IS NULL` will be used
-     * in the generated expression. Below are some examples:
-     *
-     * - `['type' => 1, 'status' => 2]` generates `(type = 1) AND (status = 2)`.
-     * - `['id' => [1, 2, 3], 'status' => 2]` generates `(id IN (1, 2, 3)) AND (status = 2)`.
-     * - `['status' => null] generates `status IS NULL`.
-     * - `['id' => $query]` generates `id IN (...sub-query...)`
-     *
-     * A condition in operator format generates the SQL expression according to the specified operator, which
-     * 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.
-     *
-     * - `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`.
-     *
-     * - `not between`: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
-     *   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.
-     *
-     * - `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'`.
-     *
-     * - `or like`: similar to the `like` operator except that `OR` is used to concatenate the `LIKE`
-     *   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.
-     *
-     * - `or not like`: similar to the `not like` operator except that `OR` is used to concatenate
-     *   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.
+     * The `$condition` parameter should be either a string (e.g. `'id=1'`) or an array.
      *
-     * - `not exists`: similar to the `exists` operator and builds a `NOT EXISTS (sub-query)` expression.
+     * @inheritdoc
      *
      * @param string|array $condition the conditions that should be put in the WHERE part.
      * @param array $params the parameters (name => value) to be bound to the query.
      * @return static the query object itself
      * @see andWhere()
      * @see orWhere()
+     * @see QueryInterface::where()
      */
     public function where($condition, $params = [])
     {

framework/db/QueryInterface.php

@@ -76,16 +76,14 @@ interface QueryInterface
     /**
      * Sets the WHERE part of the query.
      *
-     * The method requires a $condition parameter.
-     *
-     * The $condition parameter should be an array in one of the following two formats:
+     * The `$condition` specified as an array can be in one of the following two formats:
      *
      * - hash format: `['column1' => value1, 'column2' => value2, ...]`
      * - operator format: `[operator, operand1, operand2, ...]`
      *
      * A condition in hash format represents the following SQL expression in general:
      * `column1=value1 AND column2=value2 AND ...`. In case when a value is an array,
-     * an `IN` expression will be generated. And if a value is null, `IS NULL` will be used
+     * an `IN` expression will be generated. And if a value is `null`, `IS NULL` will be used
      * in the generated expression. Below are some examples:
      *
      * - `['type' => 1, 'status' => 2]` generates `(type = 1) AND (status = 2)`.
@@ -95,29 +93,32 @@ interface QueryInterface
      * A condition in operator format generates the SQL expression according to the specified operator, which
      * can be one of the followings:
      *
-     * - `and`: the operands should be concatenated together using `AND`. For example,
+     * - **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.
+     *   The method will *not* do any quoting or escaping.
+     *
+     * - **or**: similar to the `and` operator except that the operands are concatenated using `OR`.
      *
-     * - `or`: similar to the `and` operator except that the operands are concatenated using `OR`.
+     * - **not**: this will take only one operator and build the negation of it by prefixing the query string with `NOT`.
+     *   For example `['not' => ['attribute' => null]]` will result in the condition `NOT (attribute IS NULL)`.
      *
-     * - `between`: operand 1 should be the column name, and operand 2 and 3 should be the
+     * - **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`.
      *
-     * - `not between`: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
+     * - **not between**: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
      *   in the generated condition.
      *
-     * - `in`: operand 1 should be a column or DB expression, and operand 2 be an array representing
+     * - **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.
      *
-     * - `not in`: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
+     * - **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
+     * - **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
@@ -127,13 +128,13 @@ interface QueryInterface
      *   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`
+     * - **or like**: similar to the `like` operator except that `OR` is used to concatenate the `LIKE`
      *   predicates when operand 2 is an array.
      *
-     * - `not like`: similar to the `like` operator except that `LIKE` is replaced with `NOT LIKE`
+     * - **not like**: similar to the `like` operator except that `LIKE` is replaced with `NOT LIKE`
      *   in the generated condition.
      *
-     * - `or not like`: similar to the `not like` operator except that `OR` is used to concatenate
+     * - **or not like**: similar to the `not like` operator except that `OR` is used to concatenate
      *   the `NOT LIKE` predicates.
      *
      * @param string|array $condition the conditions that should be put in the WHERE part.

framework/db/QueryTrait.php

@@ -21,9 +21,9 @@ use yii\base\NotSupportedException;
 trait QueryTrait
 {
     /**
-     * @var string|array query condition. This refers to the WHERE clause in a SQL statement.
-     * For example, `age > 31 AND team = 1`.
-     * @see where()
+     * @var array query condition. This refers to the WHERE clause in a SQL statement.
+     * For example, `['age' => 31, 'team' => 1]`.
+     * @see where() for valid syntax on specifying this value.
      */
     public $where;
     /**