Changeset 30622

Timestamp:

11/28/2014 12:26:00 PM (10 years ago)

Author:

DrewAPicture

Message:

4.1 Docs Audit: Improve inline documentation in DocBlocks for various WP_Tax_Query methods, the pre_delete_term hook, and get_ancestors().

See #30469.

File:

• trunk/src/wp-includes/taxonomy.php (modified) (10 diffs)

trunk/src/wp-includes/taxonomy.php

@@ -675 +675 @@
      *
      * We store this data in a flat array because they are referenced in a
-     * number of places by WP_Query.
+     * number of places by {@see WP_Query}.
      *
      * @since 4.1.0
@@ -693 +693 @@
 
     /**
-     * Column in primary_table that represents the ID of the object.
+     * Column in 'primary_table' that represents the ID of the object.
      *
      * @since 4.1.0
@@ -705 +705 @@
      *
      * @since 3.1.0
-     * @since 4.1.0 Added support for $operator 'NOT EXISTS' and 'EXISTS'.
+     * @since 4.1.0 Added support for `$operator` 'NOT EXISTS' and 'EXISTS' values.
      * @access public
      *
@@ -739 +739 @@
 
     /**
-     * Ensure the `tax_query` argument passed to the class constructor is well-formed.
+     * Ensure the 'tax_query' argument passed to the class constructor is well-formed.
      *
      * Ensures that each query-level clause has a 'relation' key, and that
-     * each first-order clause contains all the necessary keys from $defaults.
+     * each first-order clause contains all the necessary keys from `$defaults`.
      *
      * @since 4.1.0
      * @access public
      *
-     * @param  array $queries Array of queries clauses.
+     * @param array $queries Array of queries clauses.
      * @return array Sanitized array of query clauses.
      */
@@ -842 +842 @@
      * @access protected
      *
-     * @param  array $query Tax query arguments.
-     * @return bool  Whether the query clause is a first-order clause.
+     * @param array $query Tax query arguments.
+     * @return bool Whether the query clause is a first-order clause.
      */
     protected static function is_first_order_clause( $query ) {
@@ -911 +911 @@
      * @access protected
      *
-     * @param array $query Query to parse.
+     * @param array $query Query to parse, passed by reference.
      * @param int   $depth Optional. Number of tree levels deep we currently are.
-     *              Used to calculate indentation.
+     *                     Used to calculate indentation. Default 0.
      * @return array {
      *     Array containing JOIN and WHERE SQL clauses to append to a single query array.
@@ -988 +988 @@
 
     /**
-     * Generate SQL JOIN and WHERE clauses for a first-order query clause.
+     * Generate SQL JOIN and WHERE clauses for a "first-order" query clause.
 
      * @since 4.1.0
      * @access public
      *
-     * @param  array $clause       Query clause.
-     * @param  array $parent_query Parent query array.
+     * @param array $clause       Query clause, passed by reference
+     * @param array $parent_query Parent query array.
      * @return array {
      *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
@@ -1106 +1106 @@
      * We avoid unnecessary table joins by allowing each clause to look for
      * an existing table alias that is compatible with the query that it
-     * needs to perform. An existing alias is compatible if (a) it is a
-     * sibling of $clause (ie, it's under the scope of the same relation),
-     * and (b) the combination of operator and relation between the clauses
-     * allows for a shared table join. In the case of WP_Tax_Query, this
-     * only applies to IN clauses that are connected by the relation OR.
+     * needs to perform.
+     *
+     * An existing alias is compatible if (a) it is a sibling of `$clause`
+     * (ie, it's under the scope of the same relation), and (b) the combination
+     * of operator and relation between the clauses allows for a shared table
+     * join. In the case of {@see WP_Tax_Query}, this only applies to 'IN'
+     * clauses that are connected by the relation 'OR'.
      *
      * @since 4.1.0
      * @access protected
      *
-     * @param  array       $clause       Query clause.
-     * @param  array       $parent_query Parent query of $clause.
+     * @param array       $clause       Query clause.
+     * @param array       $parent_query Parent query of $clause.
      * @return string|bool Table alias if found, otherwise false.
      */
@@ -2429 +2431 @@
      * @since 4.1.0
      *
-     * @param int $term Term ID
-     * @param string $taxonomy Taxonomy Name
+     * @param int    $term     Term ID.
+     * @param string $taxonomy Taxonomy Name.
      */
     do_action( 'pre_delete_term', $term, $taxonomy );
@@ -4331 +4333 @@
  *
  * @since 3.1.0
- * @since 4.1.0 Introduced the 'resource_type' parameter.
- *
- * @param int    $object_id     The ID of the object.
- * @param string $object_type   The type of object for which we'll be retrieving ancestors.
- *                              Accepts a post type or a taxonomy name.
- * @param string $resource_type Optional. Type of resource $object_type is. Accepts 'post_type' or 'taxonomy'.
+ * @since 4.1.0 Introduced the `$resource_type` argument.
+ *
+ * @param int    $object_id     Optional. The ID of the object. Default 0.
+ * @param string $object_type   Optional. The type of object for which we'll be retrieving
+ *                              ancestors. Accepts a post type or a taxonomy name. Default empty.
+ * @param string $resource_type Optional. Type of resource $object_type is. Accepts 'post_type'
+ *                              or 'taxonomy'. Default empty.
  * @return array An array of ancestors from lowest to highest in the hierarchy.
  */