Documenting orWhere()

lib/Cake/Model/Datasource/Database/Query.php

@@ -690,7 +690,7 @@ public function where($conditions = null, $types = [], $overwrite = false) {
 	}
 
 /**
- * Connects any previously defined set of conditions to the newly provided list
+ * Connects any previously defined set of conditions to the provided list
  * using the AND operator. This function accepts the conditions list in the same
  * format as the method `where` does, hence you can use arrays, expression objects
  * callback functions or strings.
@@ -700,9 +700,9 @@ public function where($conditions = null, $types = [], $overwrite = false) {
  * the AND operator. This function will not only operate the most recently defined
  * condition, but all the conditions as a whole.
  *
- * When using an array for defining conditions, the same rules for connecting each
- * array entry as defined in the `where` function will be used. This means that
- * each array entry will be joined to the other using the AND operator, unless
+ * When using an array for defining conditions, creating constraints form each
+ * array entry will use the same logic as with the `where()` function. This means
+ * that each array entry will be joined to the other using the AND operator, unless
  * you nest the conditions in the array using other operator.
  *
  * ##Examples:
@@ -750,6 +750,62 @@ public function andWhere($conditions, $types = []) {
 		return $this;
 	}
 
+/**
+ * Connects any previously defined set of conditions to the provided list
+ * using the OR operator. This function accepts the conditions list in the same
+ * format as the method `where` does, hence you can use arrays, expression objects
+ * callback functions or strings.
+ *
+ * It is important to notice that when calling this function, any previous set
+ * of conditions defined for this query will be treated as a single argument for
+ * the OR operator. This function will not only operate the most recently defined
+ * condition, but all the conditions as a whole.
+ *
+ * When using an array for defining conditions, creating constraints form each
+ * array entry will use the same logic as with the `where()` function. This means
+ * that each array entry will be joined to the other using the OR operator, unless
+ * you nest the conditions in the array using other operator.
+ *
+ * ##Examples:
+ *
+ * {{
+ *	$query->where(['title' => 'Hello World')->orWhere(['title' => 'Foo']);
+ * }}
+ *
+ * Will produce:
+ *
+ * ``WHERE title = 'Hello World' OR title = 'Foo'``
+ *
+ * {{
+ *	$query
+ *		->where(['OR' => ['published' => false, 'published is NULL']])
+ *		->orWhere(['author_id' => 1, 'comments_count >' => 10])
+ * }}
+ *
+ * Produces:
+ *
+ * ``WHERE (published = 0 OR published IS NULL) OR (author_id = 1 AND comments_count > 10)``
+ *
+ * {{
+ *	$query
+ *		->where(['title' => 'Foo'])
+ *		->orWhere(function($exp, $query) {
+ *			return $exp
+ *			->add(['author_id' => 1])
+ *			->or_(['author_id' => 2]);
+ *		});
+ * }}
+ *
+ * Generates the following conditions:
+ *
+ * ``WHERE (title = 'Foo') OR (author_id = 1 OR author_id = 2)``
+ *
+ * @param string|array|Expression|callback $conditions
+ * @param array $types associative array of type names used to bind values to query
+ * @see Cake\Model\Datasource\Database\Query::where()
+ * @see Cake\Model\Datasource\Database\Type
+ * @return Query
+ */
 	public function orWhere($conditions, $types = []) {
 		$this->_conjugate('where', $conditions, 'OR', $types);
 		return $this;