From 6060a66451319390b6958b0dc05c1db712d5786e Mon Sep 17 00:00:00 2001
From: Drew Jaynes <info@drewapicture.com>
Date: Thu, 20 Feb 2014 17:41:12 +0000
Subject: [PATCH] Inline documentation for various SQL clause hooks in
 wp-includes/query.php.

Covers documentation for SQL clause hooks specified for use by caching plugins, including:
* `posts_selection`
* `posts_where_request`
* `posts_groupby_request`
* `posts_join_request`
* `posts_orderby_request`
* `posts_distinct_request`
* `posts_fields_request`
* `post_limits_request`
* `posts_clauses_request`

Props dougwollison, DrewAPicture.
See #25514.


Built from https://develop.svn.wordpress.org/trunk@27207


git-svn-id: http://core.svn.wordpress.org/trunk@27064 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/query.php | 105 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 102 insertions(+), 3 deletions(-)

diff --git a/wp-includes/query.php b/wp-includes/query.php
index 73dbf3d0be..f49c53fecc 100644
--- a/wp-includes/query.php
+++ b/wp-includes/query.php
@@ -2972,20 +2972,119 @@ class WP_Query {
 			}
 		}
 
-		// Announce current selection parameters. For use by caching plugins.
+		/**
+		 * Fires to announce the query's current selection parameters.
+		 *
+		 * For use by caching plugins.
+		 *
+		 * @since 2.3.0
+		 *
+		 * @param string $selection The assembled selection query.
+		 */
 		do_action( 'posts_selection', $where . $groupby . $orderby . $limits . $join );
 
-		// Filter again for the benefit of caching plugins. Regular plugins should use the hooks above.
+		/*
+		 * Filter again for the benefit of caching plugins.
+		 * Regular plugins should use the hooks above.
+		 */
 		if ( !$q['suppress_filters'] ) {
+			/**
+			 * Filter the WHERE clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $where The WHERE clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
 			$where		= apply_filters_ref_array( 'posts_where_request',		array( $where, &$this ) );
+
+			/**
+			 * Filter the GROUP BY clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $groupby The GROUP BY clause of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by reference).
+			 */
 			$groupby	= apply_filters_ref_array( 'posts_groupby_request',		array( $groupby, &$this ) );
+
+			/**
+			 * Filter the JOIN clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $join  The JOIN clause of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
 			$join		= apply_filters_ref_array( 'posts_join_request',		array( $join, &$this ) );
+
+			/**
+			 * Filter the ORDER BY clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $orderby The ORDER BY clause of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by reference).
+			 */
 			$orderby	= apply_filters_ref_array( 'posts_orderby_request',		array( $orderby, &$this ) );
+
+			/**
+			 * Filter the DISTINCT clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $distinct The DISTINCT clause of the query.
+			 * @param WP_Query &$this    The WP_Query instance (passed by reference).
+			 */
 			$distinct	= apply_filters_ref_array( 'posts_distinct_request',	array( $distinct, &$this ) );
+
+			/**
+			 * Filter the SELECT clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $fields The SELECT clause of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by reference).
+			 */
 			$fields		= apply_filters_ref_array( 'posts_fields_request',		array( $fields, &$this ) );
+
+			/**
+			 * Filter the LIMIT clause of the query.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $limits The LIMIT clause of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by reference).
+			 */
 			$limits		= apply_filters_ref_array( 'post_limits_request',		array( $limits, &$this ) );
 
-			// Filter all clauses at once, for convenience
+			/**
+			 * Filter all query clauses at once, for convenience.
+			 *
+			 * For use by caching plugins.
+			 *
+			 * Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT,
+			 * fields (SELECT), and LIMITS clauses.
+			 *
+			 * @since 3.1.0
+			 *
+			 * @param array    $pieces The pieces of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by reference).
+			 */
 			$clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
 			foreach ( $pieces as $piece )
 				$$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';