Further join() docblock improvements

Add example for array usage, simplify docblocks, fix yoda
conditions and typos

src/Database/Query.php

@@ -388,7 +388,7 @@ class Query implements ExpressionInterface, IteratorAggregate {
 	}
 
 /**
- * Adds a single or multiple tables to be used as JOIN clauses this query.
+ * Adds a single or multiple tables to be used as JOIN clauses to this query.
  * Tables can be passed as an array of strings, an array describing the
  * join parts, an array with multiple join descriptions, or a single string.
  *
@@ -426,18 +426,18 @@ class Query implements ExpressionInterface, IteratorAggregate {
  *		'p' => [
  *			'table' => 'publishers',
  *			'type' => 'INNER',
- *			'conditions' => 'b.publisher_id = p.id AND p.name = "Cake Software Foundation"'
+ *			'conditions' => 'p.id = b.publisher_id AND p.name = "Cake Software Foundation"'
  *		]
  *	]);
  *	// LEFT JOIN authors a ON a.id = b.author_id
- *	// INNER JOIN publishers p ON b.publisher_id = p.id AND p.name = "Cake Software Foundation"
+ *	// INNER JOIN publishers p ON p.id = b.publisher_id AND p.name = "Cake Software Foundation"
  * }}}
  *
  * ### Using conditions and types
  *
  * Conditions can be expressed, as in the examples above, using a string for comparing
  * columns, or string with already quoted literal values. Additionally it is
- * possible to using conditions expressed in arrays or expression objects.
+ * possible to use conditions expressed in arrays or expression objects.
  *
  * When using arrays for expressing conditions, it is often desirable to convert
  * the literal values to the correct database representation. This is achieved
@@ -513,19 +513,33 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Adds a single LEFT JOIN clause to the query.
  *
+ * This is a shorthand method for building joins via `join()`.
+ *
+ * The table name can be passed as a string, or as an array in case it needs to
+ * be aliased:
+ *
  * {{{
- * // LEFT JOIN authors ON posts.author_id = authors.id
- * $query->leftJoin('authors', ['posts.author_id = authors.id']);
+ * // LEFT JOIN authors ON authors.id = posts.author_id
+ * $query->leftJoin('authors', 'authors.id = posts.author_id');
+ *
+ * // LEFT JOIN authors a ON a.id = posts.author_id
+ * $query->leftJoin(['a' => 'authors'], 'a.id = posts.author_id');
  * }}}
  *
- * You can pass an array in the first parameter if you need to alias
- * the table for the join:
+ * Conditions can be passed as strings, arrays, or expression objects. When
+ * using arrays it is possible to combine them with the `$types` parameter
+ * in order to define how to convert the values:
  *
  * {{{
- * // LEFT JOIN authors a ON posts.author_id = a.id
- * $query->leftJoin(['a' => 'authors'], ['posts.author_id = a.id']);
+ * $query->leftJoin(['a' => 'articles'], [
+ *		'a.posted >=' => new DateTime('-3 days'),
+ *		'a.published' => true,
+ *		'a.author_id = authors.id'
+ * ], ['a.posted' => 'datetime', 'a.published' => 'boolean']);
  * }}}
  *
+ * See `join()` for further details on conditions and types.
+ *
  * @param string|array $table The table to join with
  * @param string|array|\Cake\Database\ExpressionInterface $conditions The conditions
  * to use for joining.
@@ -540,18 +554,10 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Adds a single RIGHT JOIN clause to the query.
  *
- * {{{
- * // RIGHT JOIN authors ON posts.author_id = authors.id
- * $query->rightJoin('authors', ['posts.author_id = authors.id']);
- * }}}
- *
- * You can pass an array in the first parameter if you need to alias
- * the table for the join:
+ * This is a shorthand method for building joins via `join()`.
  *
- * {{{
- * // RIGHT JOIN authors a ON posts.author_id = a.id
- * $query->righJoin(['a' => 'authors'], ['posts.author_id = a.id']);
- * }}}
+ * The arguments of this method are identical to the `leftJoin()` shorthand, please refer
+ * to that methods description for further details.
  *
  * @param string|array $table The table to join with
  * @param string|array|\Cake\Database\ExpressionInterface $conditions The conditions
@@ -567,18 +573,10 @@ class Query implements ExpressionInterface, IteratorAggregate {
 /**
  * Adds a single INNER JOIN clause to the query.
  *
- * {{{
- * // INNER JOIN authors ON posts.author_id = authors.id
- * $query->innerJoin('authors', ['posts.author_id = authors.id']);
- * }}}
+ * This is a shorthand method for building joins via `join()`.
  *
- * You can pass an array in the first parameter if you need to alias
- * the table for the join:
- *
- * {{{
- * // INNER JOIN authors a ON posts.author_id = a.id
- * $query->innerJoin(['a' => 'authors'], ['posts.author_id = a.id']);
- * }}}
+ * The arguments of this method are identical to the `leftJoin()` shorthand, please refer
+ * to that methods description for further details.
  *
  * @param string|array $table The table to join with
  * @param string|array|\Cake\Database\ExpressionInterface $conditions The conditions