Ticket #7663: 7663.r8803.diff

query.php

@@ -1 +1 @@
 <?php
+/**
+ * WordPress Query API
+ *
+ * The query API attempts to get which part of WordPress to the user is on. It
+ * also provides functionality to getting URL query information.
+ *
+ * @link http://codex.wordpress.org/The_Loop More information on The Loop.
+ *
+ * @package WordPress
+ * @subpackage Query
+ */
 
-/*
- * The Big Query.
+/**
+ * Retrieve variable in the WP_Query class.
+ *
+ * @see WP_Query::get()
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param string $var The variable key to retrieve.
+ * @return mixed
  */
-
 function get_query_var($var) {
         global $wp_query;
 
         return $wp_query->get($var);
 }
 
+/**
+ * Set query variable.
+ *
+ * @see WP_Query::set()
+ * @since 2.2.0
+ * @uses $wp_query
+ *
+ * @param string $var Query variable key.
+ * @param mixed $value
+ * @return null
+ */
 function set_query_var($var, $value) {
         global $wp_query;
 
         return $wp_query->set($var, $value);
 }
 
+/**
+ * Setup The Loop with query parameters.
+ *
+ * This will override the current WordPress Loop and shouldn't be used more than
+ * once. This must not be used within the WordPress Loop.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param string $query
+ * @return array List of posts
+ */
 function &query_posts($query) {
         unset($GLOBALS['wp_query']);
         $GLOBALS['wp_query'] =& new WP_Query();
         return $GLOBALS['wp_query']->query($query);
 }
 
+/**
+ * Destroy the previous query and setup a new query.
+ *
+ * This should be used after {@link query_posts()} and before another {@link
+ * query_posts()}. This will remove obscure bugs that occur when the previous
+ * wp_query object is not destroyed properly before another is setup.
+ *
+ * @since 2.3.0
+ * @uses $wp_query
+ */
 function wp_reset_query() {
         unset($GLOBALS['wp_query']);
         $GLOBALS['wp_query'] =& $GLOBALS['wp_the_query'];
@@ -36 +86 @@
  * Query type checks.
  */
 
+/**
+ * Whether the current request is in WordPress admin Panel
+ *
+ * Does not inform on whether the user is an admin! Use capability checks to
+ * tell if the user should be accessing a section or not.
+ *
+ * @since 1.5.1
+ *
+ * @return bool True if inside WordPress administration pages.
+ */
 function is_admin () {
         if ( defined('WP_ADMIN') )
                 return WP_ADMIN;
         return false;
 }
 
+/**
+ * Is query requesting an archive page.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool True if page is archive.
+ */
 function is_archive () {
         global $wp_query;
 
         return $wp_query->is_archive;
 }
 
+/**
+ * Is query requesting an attachment page.
+ *
+ * @since 2.0.0
+ * @uses $wp_query
+ *
+ * @return bool True if page is attachment.
+ */
 function is_attachment () {
         global $wp_query;
 
         return $wp_query->is_attachment;
 }
 
+/**
+ * Is query requesting an author page.
+ *
+ * If the $author parameter is specified then the check will be expanded to
+ * include whether the queried author matches the one given in the parameter.
+ * You can match against integers and against strings.
+ *
+ * If matching against an integer, the ID should be used of the author for the
+ * test. If the $author is an ID and matches the author page user ID, then
+ * 'true' will be returned.
+ *
+ * If matching against strings, then the test will be matched against both the
+ * nickname and user nicename and will return true on success.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param string|int $author Optional. Is current page this author.
+ * @return bool True if page is author or $author (if set).
+ */
 function is_author ($author = '') {
         global $wp_query;
 
@@ -77 +173 @@
         return false;
 }
 
+/**
+ * Whether current page query contains a category name or given category name.
+ *
+ * The category list can contain category IDs, names, or category slugs. If any
+ * of them are part of the query, then it will return true.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param string|array $category Optional. 
+ * @return bool
+ */
 function is_category ($category = '') {
         global $wp_query;
 
@@ -100 +208 @@
         return false;
 }
 
+/**
+ * Whether the current page query has the given tag slug or contains tag.
+ *
+ * @since 2.3.0
+ * @uses $wp_query
+ *
+ * @param string|array $slug Optional. Single tag or list of tags to check for.
+ * @return bool
+ */
 function is_tag( $slug = '' ) {
         global $wp_query;
 
@@ -119 +236 @@
         return false;
 }
 
+/**
+ * Whether the current page query has the given taxonomy slug or contains taxonomy.
+ *
+ * @since 2.5.0
+ * @uses $wp_query
+ *
+ * @param string|array $slug Optional. Slug or slugs to check in current query.
+ * @return bool
+ */
 function is_tax( $slug = '' ) {
         global $wp_query;
 
@@ -138 +264 @@
         return false;
 }
 
+/**
+ * Whether the current URL is within the comments popup window.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_comments_popup () {
         global $wp_query;
 
         return $wp_query->is_comments_popup;
 }
 
+/**
+ * Whether current URL is based on a date.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_date () {
         global $wp_query;
 
         return $wp_query->is_date;
 }
 
+/**
+ * Whether current blog URL contains a day.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_day () {
         global $wp_query;
 
         return $wp_query->is_day;
 }
 
+/**
+ * Whether current page query is feed URL.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_feed () {
         global $wp_query;
 
@@ -163 +321 @@
 }
 
 /**
- * is_front_page() - Is it the front of the site, whether blog view or a WP Page?
+ * Whether current page query is the front of the site.
  *
- * @since 2.5
- * @uses is_home
- * @uses get_option
+ * @since 2.5.0
+ * @uses is_home()
+ * @uses get_option()
  *
- * @return bool True if front of site
+ * @return bool True, if front of site.
  */
 function is_front_page () {
         // most likely case
@@ -182 +340 @@
 }
 
 /**
- * is_home() - Is it the blog view homepage?
+ * Whether current page view is the blog homepage.
  *
- * @since 2.1
- * @global object $wp_query
+ * @since 1.5.0
+ * @uses $wp_query
  *
- * @return bool True if blog view homepage
+ * @return bool True if blog view homepage.
  */
 function is_home () {
         global $wp_query;
@@ -195 +353 @@
         return $wp_query->is_home;
 }
 
+/**
+ * Whether current page query contains a month.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_month () {
         global $wp_query;
 
         return $wp_query->is_month;
 }
 
+/**
+ * Whether query is page or contains given page(s).
+ *
+ * Calls the function without any parameters will only test whether the current
+ * query is of the page type. Either a list or a single item can be tested
+ * against for whether the query is a page and also is the value or one of the
+ * values in the page parameter.
+ *
+ * The parameter can contain the page ID, page title, or page name. The
+ * parameter can also be an array of those three values.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param mixed $page Either page or list of pages to test against.
+ * @return bool
+ */
 function is_page ($page = '') {
         global $wp_query;
 
@@ -224 +407 @@
         return false;
 }
 
+/**
+ * Whether query contains multiple pages for the results.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_paged () {
         global $wp_query;
 
         return $wp_query->is_paged;
 }
 
+/**
+ * Whether the current page was created by a plugin.
+ *
+ * The plugin can set this by using the global $plugin_page and setting it to
+ * true.
+ *
+ * @since 1.5.0
+ * @global bool $plugin_page Used by plugins to tell the query that current is a plugin page.
+ *
+ * @return bool
+ */
 function is_plugin_page() {
         global $plugin_page;
 
@@ -239 +441 @@
         return false;
 }
 
+/**
+ * Whether the current query is preview of post or page.
+ *
+ * @since 2.0.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_preview() {
         global $wp_query;
 
         return $wp_query->is_preview;
 }
 
+/**
+ * Whether the current query post is robots.
+ *
+ * @since 2.1.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_robots() {
         global $wp_query;
 
         return $wp_query->is_robots;
 }
 
+/**
+ * Whether current query is the result of a user search.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_search () {
         global $wp_query;
 
         return $wp_query->is_search;
 }
 
+/**
+ * Whether the current page query is single page.
+ *
+ * The parameter can contain the post ID, post title, or post name. The
+ * parameter can also be an array of those three values.
+ *
+ * This applies to other post types, attachments, pages, posts. Just means that
+ * the current query has only a single object.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @param mixed $post Either post or list of posts to test against.
+ * @return bool
+ */
 function is_single ($post = '') {
         global $wp_query;
 
@@ -280 +521 @@
         return false;
 }
 
+/**
+ * Whether is single post, is a page, or is an attachment.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_singular() {
         global $wp_query;
 
         return $wp_query->is_singular;
 }
 
+/**
+ * Whether the query contains a time.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_time () {
         global $wp_query;
 
         return $wp_query->is_time;
 }
 
+/**
+ * Whether the query is a trackback.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_trackback () {
         global $wp_query;
 
         return $wp_query->is_trackback;
 }
 
+/**
+ * Whether the query contains a year.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function is_year () {
         global $wp_query;
 
         return $wp_query->is_year;
 }
 
+/**
+ * Whether current page query is a 404 and no results for WordPress query.
+ *
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool True, if nothing is found matching WordPress Query.
+ */
 function is_404 () {
         global $wp_query;
 
@@ -314 +595 @@
  * The Loop.  Post loop control.
  */
 
+/**
+ * Whether current WordPress query has results to loop over.
+ *
+ * @see WP_Query::have_posts()
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function have_posts() {
         global $wp_query;
 
         return $wp_query->have_posts();
 }
 
+/**
+ * Whether the caller is in the Loop.
+ *
+ * @since 2.0.0
+ * @uses $wp_query
+ *
+ * @return bool True if caller is within loop, false if loop hasn't started or ended.
+ */
 function in_the_loop() {
         global $wp_query;
 
         return $wp_query->in_the_loop;
 }
 
+/**
+ * Rewind the loop posts.
+ *
+ * @see WP_Query::rewind_posts()
+ * @since 1.5.0
+ * @uses $wp_query
+ *
+ * @return null
+ */
 function rewind_posts() {
         global $wp_query;
 
         return $wp_query->rewind_posts();
 }
 
+/**
+ * Iterate the post index in the loop.
+ *
+ * @see WP_Query::the_post()
+ * @since 1.5.0
+ * @uses $wp_query
+ */
 function the_post() {
         global $wp_query;
 
@@ -342 +656 @@
  * Comments loop.
  */
 
+/**
+ * Whether there are comments to loop over.
+ *
+ * @see WP_Query::have_comments()
+ * @since 2.2.0
+ * @uses $wp_query
+ *
+ * @return bool
+ */
 function have_comments() {
         global $wp_query;
         return $wp_query->have_comments();
 }
 
+/**
+ * Iterate comment index in the comment loop.
+ *
+ * @see WP_Query::the_comment()
+ * @since 2.2.0
+ * @uses $wp_query
+ *
+ * @return object
+ */
 function the_comment() {
         global $wp_query;
         return $wp_query->the_comment();
@@ -356 +688 @@
  * WP_Query
  */
 
+/**
+ * The WordPress Query class.
+ *
+ * @link http://codex.wordpress.org/Function_Reference/WP_Query Codex page.
+ *
+ * @since 1.5.0
+ */
 class WP_Query {
+
+        /**
+         * Query string
+         *
+         * @since 1.5.0
+         * @access public
+         * @var string
+         */
         var $query;
+
+        /**
+         * Query search variables set by the user.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var array
+         */
         var $query_vars = array();
+
+        /**
+         * Holds the data for a single object that is queried.
+         *
+         * Holds the contents of a post, page, category, attachment.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var object|array
+         */
         var $queried_object;
+
+        /**
+         * The ID of the queried object.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var int
+         */
         var $queried_object_id;
+
+        /**
+         * Get post database query.
+         *
+         * @since 2.0.1
+         * @access public
+         * @var string
+         */
         var $request;
 
+        /**
+         * List of posts.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var array
+         */
         var $posts;
+
+        /**
+         * The amount of posts for the current query.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var int
+         */
         var $post_count = 0;
+
+        /**
+         * Index of the current item in the loop.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var int
+         */
         var $current_post = -1;
+
+        /**
+         * Whether the loop has started and the caller is in the loop.
+         *
+         * @since 2.0.0
+         * @access public
+         * @var bool
+         */
         var $in_the_loop = false;
+
+        /**
+         * The current post ID.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var int
+         */
         var $post;
 
+        /**
+         * The list of comments for current post.
+         *
+         * @since 2.2.0
+         * @access public
+         * @var array
+         */
         var $comments;
+
+        /**
+         * The amount of comments for the posts.
+         *
+         * @since 2.2.0
+         * @access public
+         * @var int
+         */
         var $comment_count = 0;
+
+        /**
+         * The index of the comment in the comment loop.
+         *
+         * @since 2.2.0
+         * @access public
+         * @var int
+         */
         var $current_comment = -1;
+
+        /**
+         * Current comment ID.
+         *
+         * @since 2.2.0
+         * @access public
+         * @var int
+         */
         var $comment;
 
+        /**
+         * Amount of posts if limit clause was not used.
+         *
+         * @since 2.1.0
+         * @access public
+         * @var int
+         */
         var $found_posts = 0;
+
+        /**
+         * The amount of pages.
+         *
+         * @since 2.1.0
+         * @access public
+         * @var int
+         */
         var $max_num_pages = 0;
 
+        /**
+         * Set if query is single post.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_single = false;
+
+        /**
+         * Set if query is preview of blog.
+         *
+         * @since 2.0.0
+         * @access public
+         * @var bool
+         */
         var $is_preview = false;
+
+        /**
+         * Set if query returns a page.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_page = false;
+
+        /**
+         * Set if query is an archive list.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_archive = false;
+
+        /**
+         * Set if query is part of a date.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_date = false;
+
+        /**
+         * Set if query contains a year.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_year = false;
+
+        /**
+         * Set if query contains a month.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_month = false;
+
+        /**
+         * Set if query contains a day.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_day = false;
+
+        /**
+         * Set if query contains time.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_time = false;
+
+        /**
+         * Set if query contains an author.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_author = false;
+
+        /**
+         * Set if query contains category.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_category = false;
+
+        /**
+         * Set if query contains tag.
+         *
+         * @since 2.3.0
+         * @access public
+         * @var bool
+         */
         var $is_tag = false;
+
+        /**
+         * Set if query contains taxonomy.
+         *
+         * @since 2.5.0
+         * @access public
+         * @var bool
+         */
         var $is_tax = false;
+
+        /**
+         * Set if query was part of a search result.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_search = false;
+
+        /**
+         * Set if query is feed display.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_feed = false;
+
+        /**
+         * Set if query is comment feed display.
+         *
+         * @since 2.2.0
+         * @access public
+         * @var bool
+         */
         var $is_comment_feed = false;
+
+        /**
+         * Set if query is trackback.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_trackback = false;
+
+        /**
+         * Set if query is blog homepage.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_home = false;
+
+        /**
+         * Set if query couldn't found anything.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_404 = false;
+
+        /**
+         * Set if query is within comments popup window.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_comments_popup = false;
+
+        /**
+         * Set if query is part of administration page.
+         *
+         * @since 1.5.0
+         * @access public
+         * @var bool
+         */
         var $is_admin = false;
+
+        /**
+         * Set if query is an attachment.
+         *
+         * @since 2.0.0
+         * @access public
+         * @var bool
+         */
         var $is_attachment = false;
+
+        /**
+         * Set if is single, is a page, or is an attachment.
+         *
+         * @since 2.1.0
+         * @access public
+         * @var bool
+         */
         var $is_singular = false;
+
+        /**
+         * Set if query is for robots.
+         *
+         * @since 2.1.0
+         * @access public
+         * @var bool
+         */
         var $is_robots = false;
+
+        /**
+         * Set if query contains posts.
+         *
+         * Basically, the homepage if the option isn't set for the static homepage.
+         *
+         * @since 2.1.0
+         * @access public
+         * @var bool
+         */
         var $is_posts_page = false;
 
+        /**
+         * Resets query flags to false.
+         *
+         * The query flags are what page info WordPress was able to figure out.
+         *
+         * @since 2.0.0
+         * @access private
+         */
         function init_query_flags() {
                 $this->is_single = false;
                 $this->is_page = false;
@@ -430 +1105 @@
                 $this->is_posts_page = false;
         }
 
+        /**
+         * Initiates object properties and sets default values.
+         *
+         * @since 1.5.0
+         * @access public
+         */
         function init () {
                 unset($this->posts);
                 unset($this->query);
@@ -443 +1124 @@
                 $this->init_query_flags();
         }
 
-        // Reparse the query vars.
+        /**
+         * Reparse the query vars.
+         *
+         * @since 1.5.0
+         * @access public
+         */
         function parse_query_vars() {
                 $this->parse_query('');
         }
 
+        /**
+         * Fills in the query variables, which do not exist within the parameter.
+         *
+         * @since 2.1.0
+         * @access public
+         *
+         * @param array $array Defined query variables.
+         * @return array Complete query variables with undefined ones filled in empty.
+         */
         function fill_query_vars($array) {
                 $keys = array(
                         'error'
@@ -499 +1194 @@
                 return $array;
         }
 
-        // Parse a query string and set query type booleans.
+        /**
+         * Parse a query string and set query type booleans.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @param string|array $query
+         */
         function parse_query ($query) {
                 if ( !empty($query) || !isset($this->query) ) {
                         $this->init();
@@ -707 +1409 @@
                                 $this->is_author = true;
                         }
 
-                        if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag || $this->is_tax ) )
+                        if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag ) )
                                 $this->is_archive = true;
                 }
 
@@ -791 +1493 @@
                         do_action_ref_array('parse_query', array(&$this));
         }
 
+        /**
+         * Sets the 404 property and saves whether query is feed.
+         *
+         * @since 2.0.0
+         * @access public
+         */
         function set_404() {
                 $is_feed = $this->is_feed;
 
@@ -800 +1508 @@
                 $this->is_feed = $is_feed;
         }
 
+        /**
+         * Retrieve query variable.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @param string $query_var Query variable key.
+         * @return mixed
+         */
         function get($query_var) {
                 if (isset($this->query_vars[$query_var])) {
                         return $this->query_vars[$query_var];
@@ -808 +1525 @@
                 return '';
         }
 
+        /**
+         * Set query variable.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @param string $query_var Query variable key.
+         * @param mixed $value Query variable value.
+         */
         function set($query_var, $value) {
                 $this->query_vars[$query_var] = $value;
         }
 
+        /**
+         * Retrieve the posts based on query variables.
+         *
+         * There are a few filters and actions that can be used to modify the post
+         * database query.
+         *
+         * @since 1.5.0
+         * @access public
+         * @uses do_action_ref_array() Calls 'pre_get_posts' hook before retrieving posts.
+         *
+         * @return array List of posts.
+         */
         function &get_posts() {
                 global $wpdb, $user_ID;
 
@@ -1549 +2287 @@
                         if ( !empty($sticky_posts) ) {
                                 $stickies__in = implode(',', array_map( 'absint', $sticky_posts ));
                                 $stickies = $wpdb->get_results( "SELECT * FROM $wpdb->posts WHERE $wpdb->posts.ID IN ($stickies__in)" );
-                                // TODO Make sure post is published or viewable by the current user
+                                /** @todo Make sure post is published or viewable by the current user */
                                 foreach ( $stickies as $sticky_post ) {
                                         if ( 'publish' != $sticky_post->post_status )
                                                 continue;
@@ -1572 +2310 @@
                 return $this->posts;
         }
 
+        /**
+         * Setup the next post and iterate current post index.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @return object Next post.
+         */
         function next_post() {
 
                 $this->current_post++;
@@ -1580 +2326 @@
                 return $this->post;
         }
 
+        /**
+         * Sets up the current post.
+         *
+         * Retrieves the next post, sets up the post, sets the 'in the loop'
+         * property to true.
+         *
+         * @since 1.5.0
+         * @access public
+         * @uses $post
+         * @uses do_action() Calls 'loop_start' if loop has just started
+         */
         function the_post() {
                 global $post;
                 $this->in_the_loop = true;
@@ -1590 +2347 @@
                         do_action('loop_start');
         }
 
+        /**
+         * Whether there are more posts available in the loop.
+         *
+         * Calls action 'loop_end', when the loop is complete.
+         *
+         * @since 1.5.0
+         * @access public
+         * @uses do_action() Calls 'loop_start' if loop has just started
+         *
+         * @return bool True if posts are available, false if end of loop.
+         */
         function have_posts() {
                 if ($this->current_post + 1 < $this->post_count) {
                         return true;
@@ -1603 +2371 @@
                 return false;
         }
 
+        /**
+         * Rewind the posts and reset post index.
+         *
+         * @since 1.5.0
+         * @access public
+         */
         function rewind_posts() {
                 $this->current_post = -1;
                 if ($this->post_count > 0) {
@@ -1610 +2384 @@
                 }
         }
 
+        /**
+         * Iterate current comment index and return comment object.
+         *
+         * @since 2.2.0
+         * @access public
+         *
+         * @return object Comment object.
+         */
         function next_comment() {
                 $this->current_comment++;
 
@@ -1617 +2399 @@
                 return $this->comment;
         }
 
+        /**
+         * Sets up the current comment.
+         *
+         * @since 2.2.0
+         * @access public
+         * @global object $comment Current comment.
+         * @uses do_action() Calls 'comment_loop_start' hook when first comment is processed.
+         */
         function the_comment() {
                 global $comment;
 
@@ -1627 +2417 @@
                 }
         }
 
+        /**
+         * Whether there are more comments available.
+         *
+         * Automatically rewinds comments when finished.
+         *
+         * @since 2.2.0
+         * @access public
+         *
+         * @return bool True, if more comments. False, if no more posts.
+         */
         function have_comments() {
                 if ($this->current_comment + 1 < $this->comment_count) {
                         return true;
@@ -1637 +2437 @@
                 return false;
         }
 
+        /**
+         * Rewind the comments, resets the comment index and comment to first.
+         *
+         * @since 2.2.0
+         * @access public
+         */
         function rewind_comments() {
                 $this->current_comment = -1;
                 if ($this->comment_count > 0) {
@@ -1644 +2450 @@
                 }
         }
 
+        /**
+         * Sets up the WordPress query by parsing query string.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @param string $query URL query string.
+         * @return array List of posts.
+         */
         function &query($query) {
                 $this->parse_query($query);
                 return $this->get_posts();
         }
 
+        /**
+         * Retrieve queried object.
+         *
+         * If queried object is not set, then the queried object will be set from
+         * the category, tag, taxonomy, posts page, single post, page, or author
+         * query variable. After it is set up, it will be returned.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @return object
+         */
         function get_queried_object() {
                 if (isset($this->queried_object)) {
                         return $this->queried_object;
@@ -1697 +2524 @@
                 return $this->queried_object;
         }
 
+        /**
+         * Retrieve ID of the current queried object.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @return int
+         */
         function get_queried_object_id() {
                 $this->get_queried_object();
 
@@ -1707 +2542 @@
                 return 0;
         }
 
+        /**
+         * PHP4 type constructor.
+         *
+         * Sets up the WordPress query, if parameter is not empty.
+         *
+         * @since 1.5.0
+         * @access public
+         *
+         * @param string $query URL query string.
+         * @return WP_Query
+         */
         function WP_Query ($query = '') {
                 if (! empty($query)) {
                         $this->query($query);
@@ -1714 +2560 @@
         }
 }
 
-
-// Redirect old slugs
+/**
+ * Redirect old slugs to the correct permalink.
+ *
+ * Attempts to find the current slug from the past slugs.
+ *
+ * @since 2.1.0
+ * @uses $wp_query
+ * @uses $wpdb
+ *
+ * @return null If no link is found, null is returned.
+ */
 function wp_old_slug_redirect () {
         global $wp_query;
         if ( is_404() && '' != $wp_query->query_vars['name'] ) :
@@ -1747 +2602 @@
         endif;
 }
 
-
-//
-// Private helper functions
-//
-
-// Setup global post data.
+/**
+ * Setup global post data.
+ *
+ * @since 1.5.0
+ *
+ * @param object $post Post data.
+ * @return bool True when finished.
+ */
 function setup_postdata($post) {
         global $id, $authordata, $day, $currentmonth, $page, $pages, $multipage, $more, $numpages;