Index: wp-includes/query.php
===================================================================
--- wp-includes/query.php	(revision 25634)
+++ wp-includes/query.php	(working copy)
@@ -1709,7 +1709,14 @@
 		$this->query_vars_hash = md5( serialize( $this->query_vars ) );
 		$this->query_vars_changed = false;
 
-		do_action_ref_array('parse_query', array(&$this));
+		/**
+		 * Fires actions to be run after parse_query is complete.
+		 *
+		 * @since 1.5.2
+		 *
+		 * @param WP_Query &$this The WP_Query instance (passed by reference).
+		 */
+		do_action_ref_array( 'parse_query', array( &$this ) );
 	}
 
 	/*
@@ -1903,6 +1910,13 @@
 
 		$this->tax_query = new WP_Tax_Query( $tax_query );
 
+		/**
+		 * Fires actions to be run after parse_tax_query is complete.
+		 *
+		 * @since 3.7.0
+		 *
+		 * @param WP_Query $this The WP_Query instance.
+		 */
 		do_action( 'parse_tax_query', $this );
 	}
 
@@ -2144,7 +2158,14 @@
 
 		$this->parse_query();
 
-		do_action_ref_array('pre_get_posts', array(&$this));
+		/**
+		 * Fires actions to run after parse_query and before get_posts actually begins.
+		 *
+		 * @since 2.0.0
+		 *
+		 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+		 */
+		do_action_ref_array( 'pre_get_posts', array( &$this ) );
 
 		// Shorthand.
 		$q = &$this->query_vars;
@@ -2774,8 +2795,25 @@
 		// Apply filters on where and join prior to paging so that any
 		// manipulations to them are reflected in the paging by day queries.
 		if ( !$q['suppress_filters'] ) {
-			$where = apply_filters_ref_array('posts_where', array( $where, &$this ) );
-			$join = apply_filters_ref_array('posts_join', array( $join, &$this ) );
+			/**
+			 * Filter the WHERE portion of the posts query before sending.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param string   $where The WHERE portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
+			$where = apply_filters_ref_array( 'posts_where', array( $where, &$this ) );
+
+			/**
+			 * Filter the JOIN portion of the posts query before sending.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param string   $where The JOIN portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
+			$join = apply_filters_ref_array( 'posts_join', array( $join, &$this ) );
 		}
 
 		// Paging
@@ -2806,11 +2844,55 @@
 			}
 
 			if ( !$q['suppress_filters'] ) {
-				$cjoin = apply_filters_ref_array('comment_feed_join', array( $cjoin, &$this ) );
-				$cwhere = apply_filters_ref_array('comment_feed_where', array( $cwhere, &$this ) );
-				$cgroupby = apply_filters_ref_array('comment_feed_groupby', array( $cgroupby, &$this ) );
-				$corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
-				$climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
+				/**
+				 * Filter the JOIN portion of the comments feed query before sending.
+				 *
+				 * @since 1.5.2
+				 *
+				 * @param string   $cjoin The JOIN portion of the query.
+				 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+				 */
+				$cjoin = apply_filters_ref_array( 'comment_feed_join', array( $cjoin, &$this ) );
+
+				/**
+				 * Filter the WHERE portion of the comments feed query before sending.
+				 *
+				 * @since 1.5.2
+				 *
+				 * @param string   $cwhere The WHERE portion of the query.
+				 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+				 */
+				$cwhere = apply_filters_ref_array( 'comment_feed_where', array( $cwhere, &$this ) );
+
+				/**
+				 * Filter the GROUP BY portion of the comments feed query before sending.
+				 *
+				 * @since 1.5.2
+				 *
+				 * @param string   $cgroupby The GROUP BY portion of the query.
+				 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
+				 */
+				$cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( $cgroupby, &$this ) );
+
+				/**
+				 * Filter the ORDER BY portion of the comments feed query before sending.
+				 *
+				 * @since 1.5.2
+				 *
+				 * @param string   $corderby The ORDER BY portion of the query.
+				 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
+				 */
+				$corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
+
+				/**
+				 * Filter the LIMIT portion of the comments feed query before sending.
+				 *
+				 * @since 1.5.2
+				 *
+				 * @param string   $climits The JOIN portion of the query.
+				 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+				 */
+				$climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
 			}
 			$cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
 			$corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
@@ -2836,34 +2918,182 @@
 		// Apply post-paging filters on where and join. Only plugins that
 		// manipulate paging queries should use these hooks.
 		if ( !$q['suppress_filters'] ) {
+			/**
+			 * Filter the WHERE portion of the posts query before sending.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param string   $where The WHERE portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
 			$where		= apply_filters_ref_array( 'posts_where_paged',	array( $where, &$this ) );
+
+			/**
+			 * Filter the GROUP BY portion of the posts query before sending.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param string   $groupby The GROUP BY portion of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+			 */
 			$groupby	= apply_filters_ref_array( 'posts_groupby',		array( $groupby, &$this ) );
+
+			/**
+			 * Filter the JOIN portion of the posts query before sending.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param string   $join  The JOIN portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
 			$join		= apply_filters_ref_array( 'posts_join_paged',	array( $join, &$this ) );
+
+			/**
+			 * Filter the ORDER BY portion of the posts query before sending.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param string   $orderby The ORDER BY portion of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+			 */
 			$orderby	= apply_filters_ref_array( 'posts_orderby',		array( $orderby, &$this ) );
+
+			/**
+			 * Filter the DISTINCT portion of the posts query before sending.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $distinct The DISTINCT portion of the query.
+			 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
+			 */
 			$distinct	= apply_filters_ref_array( 'posts_distinct',	array( $distinct, &$this ) );
+
+			/**
+			 * Filter the LIMIT portion of the posts query before sending.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $limits The LIMIT portion of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$limits		= apply_filters_ref_array( 'post_limits',		array( $limits, &$this ) );
+
+			/**
+			 * Filter the SELECT portion of the posts query before sending.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $fields The SELECT portion of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$fields		= apply_filters_ref_array( 'posts_fields',		array( $fields, &$this ) );
 
-			// Filter all clauses at once, for convenience
+			/**
+			 * Filter all clauses at once, for convenience.
+			 *
+			 * @since 3.1.0
+			 *
+			 * @param array    $pieces The pieces of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
+
 			foreach ( $pieces as $piece )
 				$$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
 		}
 
 		// Announce current selection parameters. For use by caching plugins.
+		/**
+		 * Fires actions to be run once post selection preperation has been completed.
+		 *
+		 * Largely 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.
 		if ( !$q['suppress_filters'] ) {
+			/**
+			 * Filter the WHERE portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $where The WHERE portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
 			$where		= apply_filters_ref_array( 'posts_where_request',		array( $where, &$this ) );
+
+			/**
+			 * Filter the GROUP BY portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $groupby The GROUP BY portion of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+			 */
 			$groupby	= apply_filters_ref_array( 'posts_groupby_request',		array( $groupby, &$this ) );
+
+			/**
+			 * Filter the JOIN portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $join  The JOIN portion of the query.
+			 * @param WP_Query &$this The WP_Query instance (passed by refrence).
+			 */
 			$join		= apply_filters_ref_array( 'posts_join_request',		array( $join, &$this ) );
+
+			/**
+			 * Filter the ORDER BY portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $orderby The ORDER BY portion of the query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+			 */
 			$orderby	= apply_filters_ref_array( 'posts_orderby_request',		array( $orderby, &$this ) );
+
+			/**
+			 * Filter the DISTINCT portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $distinct The DISTINCT portion of the query.
+			 * @param WP_Query &$this    The WP_Query instance (passed by refrence).
+			 */
 			$distinct	= apply_filters_ref_array( 'posts_distinct_request',	array( $distinct, &$this ) );
+
+			/**
+			 * Filter the SELECT portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $fields The SELECT portion of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$fields		= apply_filters_ref_array( 'posts_fields_request',		array( $fields, &$this ) );
+
+			/**
+			 * Filter the LIMIT portion of the posts query before sending.
+			 *
+			 * @since 2.5.0
+			 *
+			 * @param string   $limits The LIMIT portion of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$limits		= apply_filters_ref_array( 'post_limits_request',		array( $limits, &$this ) );
 
-			// Filter all clauses at once, for convenience
+			/**
+			 * Filter all clauses at once, for convenience.
+			 *
+			 * @since 3.1.0
+			 *
+			 * @param array    $pieces The pieces of the query.
+			 * @param WP_Query &$this  The WP_Query instance (passed by refrence).
+			 */
 			$clauses = (array) apply_filters_ref_array( 'posts_clauses_request', array( compact( $pieces ), &$this ) );
 			foreach ( $pieces as $piece )
 				$$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
@@ -2881,6 +3111,14 @@
 		$this->request = $old_request = "SELECT $found_rows $distinct $fields FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
 
 		if ( !$q['suppress_filters'] ) {
+			/**
+			 * Filter the completed SQL query before sending.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param array    $request The complete SQL query.
+			 * @param WP_Query &$this   The WP_Query instance (passed by refrence).
+			 */
 			$this->request = apply_filters_ref_array( 'posts_request', array( $this->request, &$this ) );
 		}
 
@@ -2905,6 +3143,15 @@
 		}
 
 		$split_the_query = ( $old_request == $this->request && "$wpdb->posts.*" == $fields && !empty( $limits ) && $q['posts_per_page'] < 500 );
+
+		/**
+		 * Filter the $split_the_query boolean.
+		 *
+		 * @since 3.4.0
+		 *
+		 * @param bool     $split_the_query Whether or not to split the query.
+		 * @param WP_Query $this            The WP_Query instance.
+		 */
 		$split_the_query = apply_filters( 'split_the_query', $split_the_query, $this );
 
 		if ( $split_the_query ) {
@@ -2912,6 +3159,14 @@
 
 			$this->request = "SELECT $found_rows $distinct $wpdb->posts.ID FROM $wpdb->posts $join WHERE 1=1 $where $groupby $orderby $limits";
 
+			/**
+			 * Filter the Post ID request before sending.
+			 *
+			 * @since 3.4.0
+			 *
+			 * @param string   $request The post ID request.
+			 * @param WP_Query $this    The WP_Query instance.
+			 */
 			$this->request = apply_filters( 'posts_request_ids', $this->request, $this );
 
 			$ids = $wpdb->get_col( $this->request );
@@ -2932,18 +3187,35 @@
 		if ( $this->posts )
 			$this->posts = array_map( 'get_post', $this->posts );
 
-		// Raw results filter. Prior to status checks.
 		if ( !$q['suppress_filters'] )
-			$this->posts = apply_filters_ref_array('posts_results', array( $this->posts, &$this ) );
+			/**
+			 * Filter the raw post results array, prior to status checks.
+			 *
+			 * @since 2.3.0
+			 *
+			 * @param array    $posts The post results array.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			$this->posts = apply_filters_ref_array( 'posts_results', array( $this->posts, &$this ) );
 
 		if ( !empty($this->posts) && $this->is_comment_feed && $this->is_singular ) {
-			$cjoin = apply_filters_ref_array('comment_feed_join', array( '', &$this ) );
-			$cwhere = apply_filters_ref_array('comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) );
-			$cgroupby = apply_filters_ref_array('comment_feed_groupby', array( '', &$this ) );
+			// duplicate_hook
+			$cjoin = apply_filters_ref_array( 'comment_feed_join', array( '', &$this ) );
+
+			// duplicate_hook
+			$cwhere = apply_filters_ref_array( 'comment_feed_where', array( "WHERE comment_post_ID = '{$this->posts[0]->ID}' AND comment_approved = '1'", &$this ) );
+
+			// duplicate_hook
+			$cgroupby = apply_filters_ref_array( 'comment_feed_groupby', array( '', &$this ) );
 			$cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
-			$corderby = apply_filters_ref_array('comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
+
+			// duplicate_hook
+			$corderby = apply_filters_ref_array( 'comment_feed_orderby', array( 'comment_date_gmt DESC', &$this ) );
 			$corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
-			$climits = apply_filters_ref_array('comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
+
+			// duplicate_hook
+			$climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
+
 			$comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits";
 			$this->comments = $wpdb->get_results($comments_request);
 			$this->comment_count = count($this->comments);
@@ -2978,6 +3250,14 @@
 			}
 
 			if ( $this->is_preview && $this->posts && current_user_can( $edit_cap, $this->posts[0]->ID ) )
+				/**
+				 * Filter the single post for preview mode.
+				 *
+				 * @since 2.7.0
+				 *
+				 * @param WP_Post  $post  The Post object.
+				 * @param WP_Query &$this The WP_Query instance (passed by reference).
+				 */
 				$this->posts[0] = get_post( apply_filters_ref_array( 'the_preview', array( $this->posts[0], &$this ) ) );
 		}
 
@@ -3023,7 +3303,16 @@
 		}
 
 		if ( !$q['suppress_filters'] )
-			$this->posts = apply_filters_ref_array('the_posts', array( $this->posts, &$this ) );
+			/**
+			 * Filter the array of retreived posts after they've been fetched and
+			 * internally processed.
+			 *
+			 * @since 1.5.2
+			 *
+			 * @param array    $posts The array of retrieved posts.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			$this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, &$this ) );
 
 		// Ensure that any posts added/modified via one of the filters above are
 		// of the type WP_Post and are filtered.
@@ -3060,10 +3349,26 @@
 			return;
 
 		if ( ! empty( $limits ) )
+			/**
+			 * Filter the query to run for retrieving the found posts.
+			 *
+			 * @since 2.1.0
+			 *
+			 * @param string   $query The query to run to find the found posts.
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
 			$this->found_posts = $wpdb->get_var( apply_filters_ref_array( 'found_posts_query', array( 'SELECT FOUND_ROWS()', &$this ) ) );
 		else
 			$this->found_posts = count( $this->posts );
 
+		/**
+		 * Filter the number of found posts.
+		 *
+		 * @since 2.1.0
+		 *
+		 * @param int      $found_posts The number of posts found.
+		 * @param WP_Query &$this       The WP_Query instance (passed by reference).
+		 */
 		$this->found_posts = apply_filters_ref_array( 'found_posts', array( $this->found_posts, &$this ) );
 
 		if ( ! empty( $limits ) )
@@ -3102,7 +3407,14 @@
 		$this->in_the_loop = true;
 
 		if ( $this->current_post == -1 ) // loop has just started
-			do_action_ref_array('loop_start', array(&$this));
+			/**
+			 * Fires actions to be run once the loop is started.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			do_action_ref_array( 'loop_start', array( &$this ) );
 
 		$post = $this->next_post();
 		setup_postdata($post);
@@ -3123,7 +3435,14 @@
 		if ( $this->current_post + 1 < $this->post_count ) {
 			return true;
 		} elseif ( $this->current_post + 1 == $this->post_count && $this->post_count > 0 ) {
-			do_action_ref_array('loop_end', array(&$this));
+			/**
+			 * Fires actions to be run once the loop has ended.
+			 *
+			 * @since 2.0.0
+			 *
+			 * @param WP_Query &$this The WP_Query instance (passed by reference).
+			 */
+			do_action_ref_array( 'loop_end', array( &$this ) );
 			// Do some cleaning up after the loop
 			$this->rewind_posts();
 		}
@@ -3174,7 +3493,12 @@
 		$comment = $this->next_comment();
 
 		if ( $this->current_comment == 0 ) {
-			do_action('comment_loop_start');
+			/**
+			 * Fires actions to be run once the comment loop is started.
+			 *
+			 * @since 2.2.0
+			 */
+			do_action( 'comment_loop_start' );
 		}
 	}
 
@@ -3935,7 +4259,14 @@
 		$pages = array( $post->post_content );
 	}
 
-	do_action_ref_array('the_post', array(&$post));
+	/**
+	 * Fires actions to be run once the post data has been setup.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @param WP_Post &$post The Post object (passed by reference).
+	 */
+	do_action_ref_array( 'the_post', array( &$post ) );
 
 	return true;
 }
