Inline docs for WP_Tax_Query. See #15752

git-svn-id: http://svn.automattic.com/wordpress/trunk@16854 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/query.php

@@ -1471,13 +1471,13 @@ class WP_Query {
 	}
 
 	/*
-	 * Parses various taxonomy related query vars and sets the appropriate query flags
+	 * Parses various taxonomy related query vars and sets the appropriate query flags.
 	 *
 	 * @access protected
 	 * @since 3.1.0
 	 *
 	 * @param array &$q The query variables
-	 * @return array tax query
+	 * @return WP_Tax_Query
 	 */
 	function parse_tax_query( &$q ) {
 		if ( ! empty( $q['tax_query'] ) && is_array( $q['tax_query'] ) ) {

wp-includes/taxonomy.php

@@ -506,11 +506,31 @@ function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
 }
 
 /*
- * Given a taxonomy query, generates SQL to be appended to a main query
+ * Given a taxonomy query, generates SQL to be appended to a main query.
  *
  * @since 3.1.0
  *
- * @param array $tax_query List of taxonomy queries. A single taxonomy query is an associative array:
+ * @see WP_Tax_Query
+ *
+ * @param array $tax_query A compact tax query
+ * @param string $primary_table
+ * @param string $primary_id_column
+ * @return array
+ */
+function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
+	$tax_query_obj = new WP_Tax_Query( $tax_query );
+	return $tax_query_obj->get_sql( $primary_table, $primary_id_column );
+}
+
+/**
+ * Container class for a multiple taxonomy query.
+ *
+ * @since 3.1.0
+ */
+class WP_Tax_Query {
+
+	/**
+	 * List of taxonomy queries. A single taxonomy query is an associative array:
 	 * - 'taxonomy' string The taxonomy being queried
 	 * - 'terms' string|array The list of terms
 	 * - 'field' string (optional) Which term field is being used.
@@ -522,20 +542,47 @@ function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
 	 * - 'include_children' bool (optional) Whether to include child terms.
 	 *		Default: true
 	 *
- * @param string $primary_table
+	 * @since 3.1.0
- * @param string $primary_id_column
+	 * @access public
- * @return array
+	 * @var array
 	 */
-function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
-	$tax_query_obj = new WP_Tax_Query( $tax_query );
-	return $tax_query_obj->get_sql( $primary_table, $primary_id_column );
-}
-
-class WP_Tax_Query {
-	var $relation = '';
 	var $queries = array();
 
-	function WP_Tax_Query( &$tax_query ) {
+	/**
+	 * The relation between the queries. Can be one of 'AND' or 'OR'.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 * @var string
+	 */
+	var $relation;
+
+	/**
+	 * PHP4 type constructor.
+	 *
+	 * Parses a compact tax query and sets defaults.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 *
+	 * @param array $tax_query A compact tax query:
+	 *  array(
+	 *    'relation' => 'OR',
+	 *    array(
+	 *      'taxonomy' => 'tax1',
+	 *      'terms' => array( 'term1', 'term2' ),
+	 *      'field' => 'slug',
+	 *    ),
+	 *    array(
+	 *      'taxonomy' => 'tax2',
+	 *      'terms' => array( 'term-a', 'term-b' ),
+	 *      'field' => 'slug',
+	 *    ),
+	 *  )
+	 *
+	 * @return WP_Tax_Query
+	 */
+	function WP_Tax_Query( $tax_query ) {
 		if ( isset( $tax_query['relation'] ) && strtoupper( $tax_query['relation'] ) == 'OR' ) {
 			$this->relation = 'OR';
 		} else {
@@ -562,6 +609,16 @@ class WP_Tax_Query {
 		}
 	}
 
+	/**
+	 * Generates SQL clauses to be appended to a main query.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 *
+	 * @param string $primary_table
+	 * @param string $primary_id_column
+	 * @return array
+	 */
 	function get_sql( $primary_table, $primary_id_column ) {
 		global $wpdb;
 
@@ -640,6 +697,17 @@ class WP_Tax_Query {
 		return compact( 'join', 'where' );
 	}
 
+	/**
+	 * Transforms a list of terms, from one field to another.
+	 *
+	 * @since 3.1.0
+	 * @access private
+	 *
+	 * @param array &$terms The list of terms
+	 * @param string $taxonomy The taxonomy of the terms
+	 * @param string $field The initial field
+	 * @param string $resulting_field The resulting field	 
+	 */
 	function _transform_terms( &$terms, $taxonomy, $field, $resulting_field ) {
 		global $wpdb;