WordPress.org

Make WordPress Core

Ticket #7663: 7663.r8803.diff

File 7663.r8803.diff, 25.3 KB (added by jacobsantos, 10 years ago)

Complete query.php inline documentation based off of r8803

  • query.php

     
    11<?php
     2/**
     3 * WordPress Query API
     4 *
     5 * The query API attempts to get which part of WordPress to the user is on. It
     6 * also provides functionality to getting URL query information.
     7 *
     8 * @link http://codex.wordpress.org/The_Loop More information on The Loop.
     9 *
     10 * @package WordPress
     11 * @subpackage Query
     12 */
    213
    3 /*
    4  * The Big Query.
     14/**
     15 * Retrieve variable in the WP_Query class.
     16 *
     17 * @see WP_Query::get()
     18 * @since 1.5.0
     19 * @uses $wp_query
     20 *
     21 * @param string $var The variable key to retrieve.
     22 * @return mixed
    523 */
    6 
    724function get_query_var($var) {
    825        global $wp_query;
    926
    1027        return $wp_query->get($var);
    1128}
    1229
     30/**
     31 * Set query variable.
     32 *
     33 * @see WP_Query::set()
     34 * @since 2.2.0
     35 * @uses $wp_query
     36 *
     37 * @param string $var Query variable key.
     38 * @param mixed $value
     39 * @return null
     40 */
    1341function set_query_var($var, $value) {
    1442        global $wp_query;
    1543
    1644        return $wp_query->set($var, $value);
    1745}
    1846
     47/**
     48 * Setup The Loop with query parameters.
     49 *
     50 * This will override the current WordPress Loop and shouldn't be used more than
     51 * once. This must not be used within the WordPress Loop.
     52 *
     53 * @since 1.5.0
     54 * @uses $wp_query
     55 *
     56 * @param string $query
     57 * @return array List of posts
     58 */
    1959function &query_posts($query) {
    2060        unset($GLOBALS['wp_query']);
    2161        $GLOBALS['wp_query'] =& new WP_Query();
    2262        return $GLOBALS['wp_query']->query($query);
    2363}
    2464
     65/**
     66 * Destroy the previous query and setup a new query.
     67 *
     68 * This should be used after {@link query_posts()} and before another {@link
     69 * query_posts()}. This will remove obscure bugs that occur when the previous
     70 * wp_query object is not destroyed properly before another is setup.
     71 *
     72 * @since 2.3.0
     73 * @uses $wp_query
     74 */
    2575function wp_reset_query() {
    2676        unset($GLOBALS['wp_query']);
    2777        $GLOBALS['wp_query'] =& $GLOBALS['wp_the_query'];
     
    3686 * Query type checks.
    3787 */
    3888
     89/**
     90 * Whether the current request is in WordPress admin Panel
     91 *
     92 * Does not inform on whether the user is an admin! Use capability checks to
     93 * tell if the user should be accessing a section or not.
     94 *
     95 * @since 1.5.1
     96 *
     97 * @return bool True if inside WordPress administration pages.
     98 */
    3999function is_admin () {
    40100        if ( defined('WP_ADMIN') )
    41101                return WP_ADMIN;
    42102        return false;
    43103}
    44104
     105/**
     106 * Is query requesting an archive page.
     107 *
     108 * @since 1.5.0
     109 * @uses $wp_query
     110 *
     111 * @return bool True if page is archive.
     112 */
    45113function is_archive () {
    46114        global $wp_query;
    47115
    48116        return $wp_query->is_archive;
    49117}
    50118
     119/**
     120 * Is query requesting an attachment page.
     121 *
     122 * @since 2.0.0
     123 * @uses $wp_query
     124 *
     125 * @return bool True if page is attachment.
     126 */
    51127function is_attachment () {
    52128        global $wp_query;
    53129
    54130        return $wp_query->is_attachment;
    55131}
    56132
     133/**
     134 * Is query requesting an author page.
     135 *
     136 * If the $author parameter is specified then the check will be expanded to
     137 * include whether the queried author matches the one given in the parameter.
     138 * You can match against integers and against strings.
     139 *
     140 * If matching against an integer, the ID should be used of the author for the
     141 * test. If the $author is an ID and matches the author page user ID, then
     142 * 'true' will be returned.
     143 *
     144 * If matching against strings, then the test will be matched against both the
     145 * nickname and user nicename and will return true on success.
     146 *
     147 * @since 1.5.0
     148 * @uses $wp_query
     149 *
     150 * @param string|int $author Optional. Is current page this author.
     151 * @return bool True if page is author or $author (if set).
     152 */
    57153function is_author ($author = '') {
    58154        global $wp_query;
    59155
     
    77173        return false;
    78174}
    79175
     176/**
     177 * Whether current page query contains a category name or given category name.
     178 *
     179 * The category list can contain category IDs, names, or category slugs. If any
     180 * of them are part of the query, then it will return true.
     181 *
     182 * @since 1.5.0
     183 * @uses $wp_query
     184 *
     185 * @param string|array $category Optional.
     186 * @return bool
     187 */
    80188function is_category ($category = '') {
    81189        global $wp_query;
    82190
     
    100208        return false;
    101209}
    102210
     211/**
     212 * Whether the current page query has the given tag slug or contains tag.
     213 *
     214 * @since 2.3.0
     215 * @uses $wp_query
     216 *
     217 * @param string|array $slug Optional. Single tag or list of tags to check for.
     218 * @return bool
     219 */
    103220function is_tag( $slug = '' ) {
    104221        global $wp_query;
    105222
     
    119236        return false;
    120237}
    121238
     239/**
     240 * Whether the current page query has the given taxonomy slug or contains taxonomy.
     241 *
     242 * @since 2.5.0
     243 * @uses $wp_query
     244 *
     245 * @param string|array $slug Optional. Slug or slugs to check in current query.
     246 * @return bool
     247 */
    122248function is_tax( $slug = '' ) {
    123249        global $wp_query;
    124250
     
    138264        return false;
    139265}
    140266
     267/**
     268 * Whether the current URL is within the comments popup window.
     269 *
     270 * @since 1.5.0
     271 * @uses $wp_query
     272 *
     273 * @return bool
     274 */
    141275function is_comments_popup () {
    142276        global $wp_query;
    143277
    144278        return $wp_query->is_comments_popup;
    145279}
    146280
     281/**
     282 * Whether current URL is based on a date.
     283 *
     284 * @since 1.5.0
     285 * @uses $wp_query
     286 *
     287 * @return bool
     288 */
    147289function is_date () {
    148290        global $wp_query;
    149291
    150292        return $wp_query->is_date;
    151293}
    152294
     295/**
     296 * Whether current blog URL contains a day.
     297 *
     298 * @since 1.5.0
     299 * @uses $wp_query
     300 *
     301 * @return bool
     302 */
    153303function is_day () {
    154304        global $wp_query;
    155305
    156306        return $wp_query->is_day;
    157307}
    158308
     309/**
     310 * Whether current page query is feed URL.
     311 *
     312 * @since 1.5.0
     313 * @uses $wp_query
     314 *
     315 * @return bool
     316 */
    159317function is_feed () {
    160318        global $wp_query;
    161319
     
    163321}
    164322
    165323/**
    166  * is_front_page() - Is it the front of the site, whether blog view or a WP Page?
     324 * Whether current page query is the front of the site.
    167325 *
    168  * @since 2.5
    169  * @uses is_home
    170  * @uses get_option
     326 * @since 2.5.0
     327 * @uses is_home()
     328 * @uses get_option()
    171329 *
    172  * @return bool True if front of site
     330 * @return bool True, if front of site.
    173331 */
    174332function is_front_page () {
    175333        // most likely case
     
    182340}
    183341
    184342/**
    185  * is_home() - Is it the blog view homepage?
     343 * Whether current page view is the blog homepage.
    186344 *
    187  * @since 2.1
    188  * @global object $wp_query
     345 * @since 1.5.0
     346 * @uses $wp_query
    189347 *
    190  * @return bool True if blog view homepage
     348 * @return bool True if blog view homepage.
    191349 */
    192350function is_home () {
    193351        global $wp_query;
     
    195353        return $wp_query->is_home;
    196354}
    197355
     356/**
     357 * Whether current page query contains a month.
     358 *
     359 * @since 1.5.0
     360 * @uses $wp_query
     361 *
     362 * @return bool
     363 */
    198364function is_month () {
    199365        global $wp_query;
    200366
    201367        return $wp_query->is_month;
    202368}
    203369
     370/**
     371 * Whether query is page or contains given page(s).
     372 *
     373 * Calls the function without any parameters will only test whether the current
     374 * query is of the page type. Either a list or a single item can be tested
     375 * against for whether the query is a page and also is the value or one of the
     376 * values in the page parameter.
     377 *
     378 * The parameter can contain the page ID, page title, or page name. The
     379 * parameter can also be an array of those three values.
     380 *
     381 * @since 1.5.0
     382 * @uses $wp_query
     383 *
     384 * @param mixed $page Either page or list of pages to test against.
     385 * @return bool
     386 */
    204387function is_page ($page = '') {
    205388        global $wp_query;
    206389
     
    224407        return false;
    225408}
    226409
     410/**
     411 * Whether query contains multiple pages for the results.
     412 *
     413 * @since 1.5.0
     414 * @uses $wp_query
     415 *
     416 * @return bool
     417 */
    227418function is_paged () {
    228419        global $wp_query;
    229420
    230421        return $wp_query->is_paged;
    231422}
    232423
     424/**
     425 * Whether the current page was created by a plugin.
     426 *
     427 * The plugin can set this by using the global $plugin_page and setting it to
     428 * true.
     429 *
     430 * @since 1.5.0
     431 * @global bool $plugin_page Used by plugins to tell the query that current is a plugin page.
     432 *
     433 * @return bool
     434 */
    233435function is_plugin_page() {
    234436        global $plugin_page;
    235437
     
    239441        return false;
    240442}
    241443
     444/**
     445 * Whether the current query is preview of post or page.
     446 *
     447 * @since 2.0.0
     448 * @uses $wp_query
     449 *
     450 * @return bool
     451 */
    242452function is_preview() {
    243453        global $wp_query;
    244454
    245455        return $wp_query->is_preview;
    246456}
    247457
     458/**
     459 * Whether the current query post is robots.
     460 *
     461 * @since 2.1.0
     462 * @uses $wp_query
     463 *
     464 * @return bool
     465 */
    248466function is_robots() {
    249467        global $wp_query;
    250468
    251469        return $wp_query->is_robots;
    252470}
    253471
     472/**
     473 * Whether current query is the result of a user search.
     474 *
     475 * @since 1.5.0
     476 * @uses $wp_query
     477 *
     478 * @return bool
     479 */
    254480function is_search () {
    255481        global $wp_query;
    256482
    257483        return $wp_query->is_search;
    258484}
    259485
     486/**
     487 * Whether the current page query is single page.
     488 *
     489 * The parameter can contain the post ID, post title, or post name. The
     490 * parameter can also be an array of those three values.
     491 *
     492 * This applies to other post types, attachments, pages, posts. Just means that
     493 * the current query has only a single object.
     494 *
     495 * @since 1.5.0
     496 * @uses $wp_query
     497 *
     498 * @param mixed $post Either post or list of posts to test against.
     499 * @return bool
     500 */
    260501function is_single ($post = '') {
    261502        global $wp_query;
    262503
     
    280521        return false;
    281522}
    282523
     524/**
     525 * Whether is single post, is a page, or is an attachment.
     526 *
     527 * @since 1.5.0
     528 * @uses $wp_query
     529 *
     530 * @return bool
     531 */
    283532function is_singular() {
    284533        global $wp_query;
    285534
    286535        return $wp_query->is_singular;
    287536}
    288537
     538/**
     539 * Whether the query contains a time.
     540 *
     541 * @since 1.5.0
     542 * @uses $wp_query
     543 *
     544 * @return bool
     545 */
    289546function is_time () {
    290547        global $wp_query;
    291548
    292549        return $wp_query->is_time;
    293550}
    294551
     552/**
     553 * Whether the query is a trackback.
     554 *
     555 * @since 1.5.0
     556 * @uses $wp_query
     557 *
     558 * @return bool
     559 */
    295560function is_trackback () {
    296561        global $wp_query;
    297562
    298563        return $wp_query->is_trackback;
    299564}
    300565
     566/**
     567 * Whether the query contains a year.
     568 *
     569 * @since 1.5.0
     570 * @uses $wp_query
     571 *
     572 * @return bool
     573 */
    301574function is_year () {
    302575        global $wp_query;
    303576
    304577        return $wp_query->is_year;
    305578}
    306579
     580/**
     581 * Whether current page query is a 404 and no results for WordPress query.
     582 *
     583 * @since 1.5.0
     584 * @uses $wp_query
     585 *
     586 * @return bool True, if nothing is found matching WordPress Query.
     587 */
    307588function is_404 () {
    308589        global $wp_query;
    309590
     
    314595 * The Loop.  Post loop control.
    315596 */
    316597
     598/**
     599 * Whether current WordPress query has results to loop over.
     600 *
     601 * @see WP_Query::have_posts()
     602 * @since 1.5.0
     603 * @uses $wp_query
     604 *
     605 * @return bool
     606 */
    317607function have_posts() {
    318608        global $wp_query;
    319609
    320610        return $wp_query->have_posts();
    321611}
    322612
     613/**
     614 * Whether the caller is in the Loop.
     615 *
     616 * @since 2.0.0
     617 * @uses $wp_query
     618 *
     619 * @return bool True if caller is within loop, false if loop hasn't started or ended.
     620 */
    323621function in_the_loop() {
    324622        global $wp_query;
    325623
    326624        return $wp_query->in_the_loop;
    327625}
    328626
     627/**
     628 * Rewind the loop posts.
     629 *
     630 * @see WP_Query::rewind_posts()
     631 * @since 1.5.0
     632 * @uses $wp_query
     633 *
     634 * @return null
     635 */
    329636function rewind_posts() {
    330637        global $wp_query;
    331638
    332639        return $wp_query->rewind_posts();
    333640}
    334641
     642/**
     643 * Iterate the post index in the loop.
     644 *
     645 * @see WP_Query::the_post()
     646 * @since 1.5.0
     647 * @uses $wp_query
     648 */
    335649function the_post() {
    336650        global $wp_query;
    337651
     
    342656 * Comments loop.
    343657 */
    344658
     659/**
     660 * Whether there are comments to loop over.
     661 *
     662 * @see WP_Query::have_comments()
     663 * @since 2.2.0
     664 * @uses $wp_query
     665 *
     666 * @return bool
     667 */
    345668function have_comments() {
    346669        global $wp_query;
    347670        return $wp_query->have_comments();
    348671}
    349672
     673/**
     674 * Iterate comment index in the comment loop.
     675 *
     676 * @see WP_Query::the_comment()
     677 * @since 2.2.0
     678 * @uses $wp_query
     679 *
     680 * @return object
     681 */
    350682function the_comment() {
    351683        global $wp_query;
    352684        return $wp_query->the_comment();
     
    356688 * WP_Query
    357689 */
    358690
     691/**
     692 * The WordPress Query class.
     693 *
     694 * @link http://codex.wordpress.org/Function_Reference/WP_Query Codex page.
     695 *
     696 * @since 1.5.0
     697 */
    359698class WP_Query {
     699
     700        /**
     701         * Query string
     702         *
     703         * @since 1.5.0
     704         * @access public
     705         * @var string
     706         */
    360707        var $query;
     708
     709        /**
     710         * Query search variables set by the user.
     711         *
     712         * @since 1.5.0
     713         * @access public
     714         * @var array
     715         */
    361716        var $query_vars = array();
     717
     718        /**
     719         * Holds the data for a single object that is queried.
     720         *
     721         * Holds the contents of a post, page, category, attachment.
     722         *
     723         * @since 1.5.0
     724         * @access public
     725         * @var object|array
     726         */
    362727        var $queried_object;
     728
     729        /**
     730         * The ID of the queried object.
     731         *
     732         * @since 1.5.0
     733         * @access public
     734         * @var int
     735         */
    363736        var $queried_object_id;
     737
     738        /**
     739         * Get post database query.
     740         *
     741         * @since 2.0.1
     742         * @access public
     743         * @var string
     744         */
    364745        var $request;
    365746
     747        /**
     748         * List of posts.
     749         *
     750         * @since 1.5.0
     751         * @access public
     752         * @var array
     753         */
    366754        var $posts;
     755
     756        /**
     757         * The amount of posts for the current query.
     758         *
     759         * @since 1.5.0
     760         * @access public
     761         * @var int
     762         */
    367763        var $post_count = 0;
     764
     765        /**
     766         * Index of the current item in the loop.
     767         *
     768         * @since 1.5.0
     769         * @access public
     770         * @var int
     771         */
    368772        var $current_post = -1;
     773
     774        /**
     775         * Whether the loop has started and the caller is in the loop.
     776         *
     777         * @since 2.0.0
     778         * @access public
     779         * @var bool
     780         */
    369781        var $in_the_loop = false;
     782
     783        /**
     784         * The current post ID.
     785         *
     786         * @since 1.5.0
     787         * @access public
     788         * @var int
     789         */
    370790        var $post;
    371791
     792        /**
     793         * The list of comments for current post.
     794         *
     795         * @since 2.2.0
     796         * @access public
     797         * @var array
     798         */
    372799        var $comments;
     800
     801        /**
     802         * The amount of comments for the posts.
     803         *
     804         * @since 2.2.0
     805         * @access public
     806         * @var int
     807         */
    373808        var $comment_count = 0;
     809
     810        /**
     811         * The index of the comment in the comment loop.
     812         *
     813         * @since 2.2.0
     814         * @access public
     815         * @var int
     816         */
    374817        var $current_comment = -1;
     818
     819        /**
     820         * Current comment ID.
     821         *
     822         * @since 2.2.0
     823         * @access public
     824         * @var int
     825         */
    375826        var $comment;
    376827
     828        /**
     829         * Amount of posts if limit clause was not used.
     830         *
     831         * @since 2.1.0
     832         * @access public
     833         * @var int
     834         */
    377835        var $found_posts = 0;
     836
     837        /**
     838         * The amount of pages.
     839         *
     840         * @since 2.1.0
     841         * @access public
     842         * @var int
     843         */
    378844        var $max_num_pages = 0;
    379845
     846        /**
     847         * Set if query is single post.
     848         *
     849         * @since 1.5.0
     850         * @access public
     851         * @var bool
     852         */
    380853        var $is_single = false;
     854
     855        /**
     856         * Set if query is preview of blog.
     857         *
     858         * @since 2.0.0
     859         * @access public
     860         * @var bool
     861         */
    381862        var $is_preview = false;
     863
     864        /**
     865         * Set if query returns a page.
     866         *
     867         * @since 1.5.0
     868         * @access public
     869         * @var bool
     870         */
    382871        var $is_page = false;
     872
     873        /**
     874         * Set if query is an archive list.
     875         *
     876         * @since 1.5.0
     877         * @access public
     878         * @var bool
     879         */
    383880        var $is_archive = false;
     881
     882        /**
     883         * Set if query is part of a date.
     884         *
     885         * @since 1.5.0
     886         * @access public
     887         * @var bool
     888         */
    384889        var $is_date = false;
     890
     891        /**
     892         * Set if query contains a year.
     893         *
     894         * @since 1.5.0
     895         * @access public
     896         * @var bool
     897         */
    385898        var $is_year = false;
     899
     900        /**
     901         * Set if query contains a month.
     902         *
     903         * @since 1.5.0
     904         * @access public
     905         * @var bool
     906         */
    386907        var $is_month = false;
     908
     909        /**
     910         * Set if query contains a day.
     911         *
     912         * @since 1.5.0
     913         * @access public
     914         * @var bool
     915         */
    387916        var $is_day = false;
     917
     918        /**
     919         * Set if query contains time.
     920         *
     921         * @since 1.5.0
     922         * @access public
     923         * @var bool
     924         */
    388925        var $is_time = false;
     926
     927        /**
     928         * Set if query contains an author.
     929         *
     930         * @since 1.5.0
     931         * @access public
     932         * @var bool
     933         */
    389934        var $is_author = false;
     935
     936        /**
     937         * Set if query contains category.
     938         *
     939         * @since 1.5.0
     940         * @access public
     941         * @var bool
     942         */
    390943        var $is_category = false;
     944
     945        /**
     946         * Set if query contains tag.
     947         *
     948         * @since 2.3.0
     949         * @access public
     950         * @var bool
     951         */
    391952        var $is_tag = false;
     953
     954        /**
     955         * Set if query contains taxonomy.
     956         *
     957         * @since 2.5.0
     958         * @access public
     959         * @var bool
     960         */
    392961        var $is_tax = false;
     962
     963        /**
     964         * Set if query was part of a search result.
     965         *
     966         * @since 1.5.0
     967         * @access public
     968         * @var bool
     969         */
    393970        var $is_search = false;
     971
     972        /**
     973         * Set if query is feed display.
     974         *
     975         * @since 1.5.0
     976         * @access public
     977         * @var bool
     978         */
    394979        var $is_feed = false;
     980
     981        /**
     982         * Set if query is comment feed display.
     983         *
     984         * @since 2.2.0
     985         * @access public
     986         * @var bool
     987         */
    395988        var $is_comment_feed = false;
     989
     990        /**
     991         * Set if query is trackback.
     992         *
     993         * @since 1.5.0
     994         * @access public
     995         * @var bool
     996         */
    396997        var $is_trackback = false;
     998
     999        /**
     1000         * Set if query is blog homepage.
     1001         *
     1002         * @since 1.5.0
     1003         * @access public
     1004         * @var bool
     1005         */
    3971006        var $is_home = false;
     1007
     1008        /**
     1009         * Set if query couldn't found anything.
     1010         *
     1011         * @since 1.5.0
     1012         * @access public
     1013         * @var bool
     1014         */
    3981015        var $is_404 = false;
     1016
     1017        /**
     1018         * Set if query is within comments popup window.
     1019         *
     1020         * @since 1.5.0
     1021         * @access public
     1022         * @var bool
     1023         */
    3991024        var $is_comments_popup = false;
     1025
     1026        /**
     1027         * Set if query is part of administration page.
     1028         *
     1029         * @since 1.5.0
     1030         * @access public
     1031         * @var bool
     1032         */
    4001033        var $is_admin = false;
     1034
     1035        /**
     1036         * Set if query is an attachment.
     1037         *
     1038         * @since 2.0.0
     1039         * @access public
     1040         * @var bool
     1041         */
    4011042        var $is_attachment = false;
     1043
     1044        /**
     1045         * Set if is single, is a page, or is an attachment.
     1046         *
     1047         * @since 2.1.0
     1048         * @access public
     1049         * @var bool
     1050         */
    4021051        var $is_singular = false;
     1052
     1053        /**
     1054         * Set if query is for robots.
     1055         *
     1056         * @since 2.1.0
     1057         * @access public
     1058         * @var bool
     1059         */
    4031060        var $is_robots = false;
     1061
     1062        /**
     1063         * Set if query contains posts.
     1064         *
     1065         * Basically, the homepage if the option isn't set for the static homepage.
     1066         *
     1067         * @since 2.1.0
     1068         * @access public
     1069         * @var bool
     1070         */
    4041071        var $is_posts_page = false;
    4051072
     1073        /**
     1074         * Resets query flags to false.
     1075         *
     1076         * The query flags are what page info WordPress was able to figure out.
     1077         *
     1078         * @since 2.0.0
     1079         * @access private
     1080         */
    4061081        function init_query_flags() {
    4071082                $this->is_single = false;
    4081083                $this->is_page = false;
     
    4301105                $this->is_posts_page = false;
    4311106        }
    4321107
     1108        /**
     1109         * Initiates object properties and sets default values.
     1110         *
     1111         * @since 1.5.0
     1112         * @access public
     1113         */
    4331114        function init () {
    4341115                unset($this->posts);
    4351116                unset($this->query);
     
    4431124                $this->init_query_flags();
    4441125        }
    4451126
    446         // Reparse the query vars.
     1127        /**
     1128         * Reparse the query vars.
     1129         *
     1130         * @since 1.5.0
     1131         * @access public
     1132         */
    4471133        function parse_query_vars() {
    4481134                $this->parse_query('');
    4491135        }
    4501136
     1137        /**
     1138         * Fills in the query variables, which do not exist within the parameter.
     1139         *
     1140         * @since 2.1.0
     1141         * @access public
     1142         *
     1143         * @param array $array Defined query variables.
     1144         * @return array Complete query variables with undefined ones filled in empty.
     1145         */
    4511146        function fill_query_vars($array) {
    4521147                $keys = array(
    4531148                        'error'
     
    4991194                return $array;
    5001195        }
    5011196
    502         // Parse a query string and set query type booleans.
     1197        /**
     1198         * Parse a query string and set query type booleans.
     1199         *
     1200         * @since 1.5.0
     1201         * @access public
     1202         *
     1203         * @param string|array $query
     1204         */
    5031205        function parse_query ($query) {
    5041206                if ( !empty($query) || !isset($this->query) ) {
    5051207                        $this->init();
     
    7071409                                $this->is_author = true;
    7081410                        }
    7091411
    710                         if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag || $this->is_tax ) )
     1412                        if ( ($this->is_date || $this->is_author || $this->is_category || $this->is_tag ) )
    7111413                                $this->is_archive = true;
    7121414                }
    7131415
     
    7911493                        do_action_ref_array('parse_query', array(&$this));
    7921494        }
    7931495
     1496        /**
     1497         * Sets the 404 property and saves whether query is feed.
     1498         *
     1499         * @since 2.0.0
     1500         * @access public
     1501         */
    7941502        function set_404() {
    7951503                $is_feed = $this->is_feed;
    7961504
     
    8001508                $this->is_feed = $is_feed;
    8011509        }
    8021510
     1511        /**
     1512         * Retrieve query variable.
     1513         *
     1514         * @since 1.5.0
     1515         * @access public
     1516         *
     1517         * @param string $query_var Query variable key.
     1518         * @return mixed
     1519         */
    8031520        function get($query_var) {
    8041521                if (isset($this->query_vars[$query_var])) {
    8051522                        return $this->query_vars[$query_var];
     
    8081525                return '';
    8091526        }
    8101527
     1528        /**
     1529         * Set query variable.
     1530         *
     1531         * @since 1.5.0
     1532         * @access public
     1533         *
     1534         * @param string $query_var Query variable key.
     1535         * @param mixed $value Query variable value.
     1536         */
    8111537        function set($query_var, $value) {
    8121538                $this->query_vars[$query_var] = $value;
    8131539        }
    8141540
     1541        /**
     1542         * Retrieve the posts based on query variables.
     1543         *
     1544         * There are a few filters and actions that can be used to modify the post
     1545         * database query.
     1546         *
     1547         * @since 1.5.0
     1548         * @access public
     1549         * @uses do_action_ref_array() Calls 'pre_get_posts' hook before retrieving posts.
     1550         *
     1551         * @return array List of posts.
     1552         */
    8151553        function &get_posts() {
    8161554                global $wpdb, $user_ID;
    8171555
     
    15492287                        if ( !empty($sticky_posts) ) {
    15502288                                $stickies__in = implode(',', array_map( 'absint', $sticky_posts ));
    15512289                                $stickies = $wpdb->get_results( "SELECT * FROM $wpdb->posts WHERE $wpdb->posts.ID IN ($stickies__in)" );
    1552                                 // TODO Make sure post is published or viewable by the current user
     2290                                /** @todo Make sure post is published or viewable by the current user */
    15532291                                foreach ( $stickies as $sticky_post ) {
    15542292                                        if ( 'publish' != $sticky_post->post_status )
    15552293                                                continue;
     
    15722310                return $this->posts;
    15732311        }
    15742312
     2313        /**
     2314         * Setup the next post and iterate current post index.
     2315         *
     2316         * @since 1.5.0
     2317         * @access public
     2318         *
     2319         * @return object Next post.
     2320         */
    15752321        function next_post() {
    15762322
    15772323                $this->current_post++;
     
    15802326                return $this->post;
    15812327        }
    15822328
     2329        /**
     2330         * Sets up the current post.
     2331         *
     2332         * Retrieves the next post, sets up the post, sets the 'in the loop'
     2333         * property to true.
     2334         *
     2335         * @since 1.5.0
     2336         * @access public
     2337         * @uses $post
     2338         * @uses do_action() Calls 'loop_start' if loop has just started
     2339         */
    15832340        function the_post() {
    15842341                global $post;
    15852342                $this->in_the_loop = true;
     
    15902347                        do_action('loop_start');
    15912348        }
    15922349
     2350        /**
     2351         * Whether there are more posts available in the loop.
     2352         *
     2353         * Calls action 'loop_end', when the loop is complete.
     2354         *
     2355         * @since 1.5.0
     2356         * @access public
     2357         * @uses do_action() Calls 'loop_start' if loop has just started
     2358         *
     2359         * @return bool True if posts are available, false if end of loop.
     2360         */
    15932361        function have_posts() {
    15942362                if ($this->current_post + 1 < $this->post_count) {
    15952363                        return true;
     
    16032371                return false;
    16042372        }
    16052373
     2374        /**
     2375         * Rewind the posts and reset post index.
     2376         *
     2377         * @since 1.5.0
     2378         * @access public
     2379         */
    16062380        function rewind_posts() {
    16072381                $this->current_post = -1;
    16082382                if ($this->post_count > 0) {
     
    16102384                }
    16112385        }
    16122386
     2387        /**
     2388         * Iterate current comment index and return comment object.
     2389         *
     2390         * @since 2.2.0
     2391         * @access public
     2392         *
     2393         * @return object Comment object.
     2394         */
    16132395        function next_comment() {
    16142396                $this->current_comment++;
    16152397
     
    16172399                return $this->comment;
    16182400        }
    16192401
     2402        /**
     2403         * Sets up the current comment.
     2404         *
     2405         * @since 2.2.0
     2406         * @access public
     2407         * @global object $comment Current comment.
     2408         * @uses do_action() Calls 'comment_loop_start' hook when first comment is processed.
     2409         */
    16202410        function the_comment() {
    16212411                global $comment;
    16222412
     
    16272417                }
    16282418        }
    16292419
     2420        /**
     2421         * Whether there are more comments available.
     2422         *
     2423         * Automatically rewinds comments when finished.
     2424         *
     2425         * @since 2.2.0
     2426         * @access public
     2427         *
     2428         * @return bool True, if more comments. False, if no more posts.
     2429         */
    16302430        function have_comments() {
    16312431                if ($this->current_comment + 1 < $this->comment_count) {
    16322432                        return true;
     
    16372437                return false;
    16382438        }
    16392439
     2440        /**
     2441         * Rewind the comments, resets the comment index and comment to first.
     2442         *
     2443         * @since 2.2.0
     2444         * @access public
     2445         */
    16402446        function rewind_comments() {
    16412447                $this->current_comment = -1;
    16422448                if ($this->comment_count > 0) {
     
    16442450                }
    16452451        }
    16462452
     2453        /**
     2454         * Sets up the WordPress query by parsing query string.
     2455         *
     2456         * @since 1.5.0
     2457         * @access public
     2458         *
     2459         * @param string $query URL query string.
     2460         * @return array List of posts.
     2461         */
    16472462        function &query($query) {
    16482463                $this->parse_query($query);
    16492464                return $this->get_posts();
    16502465        }
    16512466
     2467        /**
     2468         * Retrieve queried object.
     2469         *
     2470         * If queried object is not set, then the queried object will be set from
     2471         * the category, tag, taxonomy, posts page, single post, page, or author
     2472         * query variable. After it is set up, it will be returned.
     2473         *
     2474         * @since 1.5.0
     2475         * @access public
     2476         *
     2477         * @return object
     2478         */
    16522479        function get_queried_object() {
    16532480                if (isset($this->queried_object)) {
    16542481                        return $this->queried_object;
     
    16972524                return $this->queried_object;
    16982525        }
    16992526
     2527        /**
     2528         * Retrieve ID of the current queried object.
     2529         *
     2530         * @since 1.5.0
     2531         * @access public
     2532         *
     2533         * @return int
     2534         */
    17002535        function get_queried_object_id() {
    17012536                $this->get_queried_object();
    17022537
     
    17072542                return 0;
    17082543        }
    17092544
     2545        /**
     2546         * PHP4 type constructor.
     2547         *
     2548         * Sets up the WordPress query, if parameter is not empty.
     2549         *
     2550         * @since 1.5.0
     2551         * @access public
     2552         *
     2553         * @param string $query URL query string.
     2554         * @return WP_Query
     2555         */
    17102556        function WP_Query ($query = '') {
    17112557                if (! empty($query)) {
    17122558                        $this->query($query);
     
    17142560        }
    17152561}
    17162562
    1717 
    1718 // Redirect old slugs
     2563/**
     2564 * Redirect old slugs to the correct permalink.
     2565 *
     2566 * Attempts to find the current slug from the past slugs.
     2567 *
     2568 * @since 2.1.0
     2569 * @uses $wp_query
     2570 * @uses $wpdb
     2571 *
     2572 * @return null If no link is found, null is returned.
     2573 */
    17192574function wp_old_slug_redirect () {
    17202575        global $wp_query;
    17212576        if ( is_404() && '' != $wp_query->query_vars['name'] ) :
     
    17472602        endif;
    17482603}
    17492604
    1750 
    1751 //
    1752 // Private helper functions
    1753 //
    1754 
    1755 // Setup global post data.
     2605/**
     2606 * Setup global post data.
     2607 *
     2608 * @since 1.5.0
     2609 *
     2610 * @param object $post Post data.
     2611 * @return bool True when finished.
     2612 */
    17562613function setup_postdata($post) {
    17572614        global $id, $authordata, $day, $currentmonth, $page, $pages, $multipage, $more, $numpages;
    17582615