WordPress.org

Make WordPress Core

Changeset 32620


Ignore:
Timestamp:
05/27/2015 06:14:08 PM (6 years ago)
Author:
wonderboymusic
Message:

Add missing doc blocks to query.php.
Clarify @return values where necessary.
Some wrapper functions don't need to return if the function they wrap doesn't return.

See #32444.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/query.php

    r32116 r32620  
    1515 * Retrieve variable in the WP_Query class.
    1616 *
    17  * @see WP_Query::get()
    1817 * @since 1.5.0
    19  * @uses $wp_query
     18 *
     19 * @global WP_Query $wp_query
    2020 *
    2121 * @param string $var       The variable key to retrieve.
     
    2525function get_query_var( $var, $default = '' ) {
    2626    global $wp_query;
    27 
    2827    return $wp_query->get( $var, $default );
    2928}
     
    3231 * Retrieve the currently-queried object. Wrapper for $wp_query->get_queried_object()
    3332 *
    34  * @uses WP_Query::get_queried_object
    35  *
    3633 * @since 3.1.0
    3734 * @access public
     35 *
     36 * @global WP_Query $wp_query
    3837 *
    3938 * @return object
     
    4746 * Retrieve ID of the current queried object. Wrapper for $wp_query->get_queried_object_id()
    4847 *
    49  * @uses WP_Query::get_queried_object_id()
    50  *
    5148 * @since 3.1.0
    5249 * @access public
     50 *
     51 * @global WP_Query $wp_query
    5352 *
    5453 * @return int
     
    6261 * Set query variable.
    6362 *
    64  * @see WP_Query::set()
    6563 * @since 2.2.0
    66  * @uses $wp_query
    67  *
    68  * @param string $var Query variable key.
    69  * @param mixed $value
    70  * @return null
     64 *
     65 * @global WP_Query $wp_query
     66 *
     67 * @param string $var   Query variable key.
     68 * @param mixed  $value
    7169 */
    72 function set_query_var($var, $value) {
     70function set_query_var( $var, $value ) {
    7371    global $wp_query;
    74 
    75     return $wp_query->set($var, $value);
     72    $wp_query->set( $var, $value );
    7673}
    7774
     
    8380 *
    8481 * @since 1.5.0
    85  * @uses $wp_query
     82 *
     83 * @global WP_Query $wp_query
    8684 *
    8785 * @param string $query
     
    10199 *
    102100 * @since 2.3.0
    103  * @uses $wp_query
     101 *
     102 * @global WP_Query $wp_query
     103 * @global WP_Query $wp_the_query
    104104 */
    105105function wp_reset_query() {
     
    113113 *
    114114 * @since 3.0.0
    115  * @uses $wp_query
     115 *
     116 * @global WP_Query $wp_query
    116117 */
    117118function wp_reset_postdata() {
     
    132133 * Month, Year, Category, Author, Post Type archive...
    133134 *
    134  * @see WP_Query::is_archive()
    135135 * @since 1.5.0
    136  * @uses $wp_query
     136 *
     137 * @global WP_Query $wp_query
    137138 *
    138139 * @return bool
     
    152153 * Is the query for an existing post type archive page?
    153154 *
    154  * @see WP_Query::is_post_type_archive()
    155155 * @since 3.1.0
    156  * @uses $wp_query
    157  *
    158  * @param mixed $post_types Optional. Post type or array of posts types to check against.
     156 *
     157 * @global WP_Query $wp_query
     158 *
     159 * @param string|array $post_types Optional. Post type or array of posts types to check against.
    159160 * @return bool
    160161 */
     
    173174 * Is the query for an existing attachment page?
    174175 *
    175  * @see WP_Query::is_attachment()
    176176 * @since 2.0.0
    177  * @uses $wp_query
     177 *
     178 * @global WP_Query $wp_query
    178179 *
    179180 * @param int|string|array|object $attachment Attachment ID, title, slug, or array of such.
     
    197198 * check if the query is for one of the authors specified.
    198199 *
    199  * @see WP_Query::is_author()
    200200 * @since 1.5.0
    201  * @uses $wp_query
     201 *
     202 * @global WP_Query $wp_query
    202203 *
    203204 * @param mixed $author Optional. User ID, nickname, nicename, or array of User IDs, nicknames, and nicenames
     
    221222 * check if the query is for one of the categories specified.
    222223 *
    223  * @see WP_Query::is_category()
    224224 * @since 1.5.0
    225  * @uses $wp_query
     225 *
     226 * @global WP_Query $wp_query
    226227 *
    227228 * @param mixed $category Optional. Category ID, name, slug, or array of Category IDs, names, and slugs.
     
    245246 * check if the query is for one of the tags specified.
    246247 *
    247  * @see WP_Query::is_tag()
    248248 * @since 2.3.0
    249  * @uses $wp_query
     249 *
     250 * @global WP_Query $wp_query
    250251 *
    251252 * @param mixed $tag Optional. Tag ID, name, slug, or array of Tag IDs, names, and slugs.
     
    273274 * specified.
    274275 *
    275  * @see WP_Query::is_tax()
    276276 * @since 2.5.0
    277  * @uses $wp_query
    278  *
    279  * @param string|array $taxonomy Optional. Taxonomy slug or slugs.
    280  * @param int|string|array $term Optional. Term ID, name, slug or array of Term IDs, names, and slugs.
     277 *
     278 * @global WP_Query $wp_query
     279 *
     280 * @param string|array     $taxonomy Optional. Taxonomy slug or slugs.
     281 * @param int|string|array $term     Optional. Term ID, name, slug or array of Term IDs, names, and slugs.
    281282 * @return bool
    282283 */
     
    295296 * Whether the current URL is within the comments popup window.
    296297 *
    297  * @see WP_Query::is_comments_popup()
    298298 * @since 1.5.0
    299  * @uses $wp_query
     299 *
     300 * @global WP_Query $wp_query
    300301 *
    301302 * @return bool
     
    315316 * Is the query for an existing date archive?
    316317 *
    317  * @see WP_Query::is_date()
    318318 * @since 1.5.0
    319  * @uses $wp_query
     319 *
     320 * @global WP_Query $wp_query
    320321 *
    321322 * @return bool
     
    335336 * Is the query for an existing day archive?
    336337 *
    337  * @see WP_Query::is_day()
    338338 * @since 1.5.0
    339  * @uses $wp_query
     339 *
     340 * @global WP_Query $wp_query
    340341 *
    341342 * @return bool
     
    355356 * Is the query for a feed?
    356357 *
    357  * @see WP_Query::is_feed()
    358358 * @since 1.5.0
    359  * @uses $wp_query
     359 *
     360 * @global WP_Query $wp_query
    360361 *
    361362 * @param string|array $feeds Optional feed types to check.
     
    376377 * Is the query for a comments feed?
    377378 *
    378  * @see WP_Query::is_comments_feed()
    379379 * @since 3.0.0
    380  * @uses $wp_query
     380 *
     381 * @global WP_Query $wp_query
    381382 *
    382383 * @return bool
     
    405406 * Otherwise the same as @see is_home()
    406407 *
    407  * @see WP_Query::is_front_page()
    408408 * @since 2.5.0
     409 *
     410 * @global WP_Query $wp_query
    409411 *
    410412 * @return bool True, if front of site.
     
    433435 * @see is_front_page()
    434436 *
    435  * @see WP_Query::is_home()
    436437 * @since 1.5.0
    437  * @uses $wp_query
     438 *
     439 * @global WP_Query $wp_query
    438440 *
    439441 * @return bool True if blog view homepage.
     
    453455 * Is the query for an existing month archive?
    454456 *
    455  * @see WP_Query::is_month()
    456457 * @since 1.5.0
    457  * @uses $wp_query
     458 *
     459 * @global WP_Query $wp_query
    458460 *
    459461 * @return bool
     
    479481 * @see is_singular()
    480482 *
    481  * @see WP_Query::is_page()
    482483 * @since 1.5.0
    483  * @uses $wp_query
     484 *
     485 * @global WP_Query $wp_query
    484486 *
    485487 * @param mixed $page Page ID, title, slug, or array of such.
     
    500502 * Is the query for paged result and not for the first page?
    501503 *
    502  * @see WP_Query::is_paged()
    503504 * @since 1.5.0
    504  * @uses $wp_query
     505 *
     506 * @global WP_Query $wp_query
    505507 *
    506508 * @return bool
     
    520522 * Is the query for a post or page preview?
    521523 *
    522  * @see WP_Query::is_preview()
    523524 * @since 2.0.0
    524  * @uses $wp_query
     525 *
     526 * @global WP_Query $wp_query
    525527 *
    526528 * @return bool
     
    540542 * Is the query for the robots file?
    541543 *
    542  * @see WP_Query::is_robots()
    543544 * @since 2.1.0
    544  * @uses $wp_query
     545 *
     546 * @global WP_Query $wp_query
    545547 *
    546548 * @return bool
     
    560562 * Is the query for a search?
    561563 *
    562  * @see WP_Query::is_search()
    563564 * @since 1.5.0
    564  * @uses $wp_query
     565 *
     566 * @global WP_Query $wp_query
    565567 *
    566568 * @return bool
     
    588590 * @see is_singular()
    589591 *
    590  * @see WP_Query::is_single()
    591592 * @since 1.5.0
    592  * @uses $wp_query
     593 *
     594 * @global WP_Query $wp_query
    593595 *
    594596 * @param mixed $post Post ID, title, slug, or array of such.
     
    615617 * @see is_single()
    616618 *
    617  * @see WP_Query::is_singular()
    618619 * @since 1.5.0
    619  * @uses $wp_query
     620 *
     621 * @global WP_Query $wp_query
    620622 *
    621623 * @param mixed $post_types Optional. Post Type or array of Post Types
     
    636638 * Is the query for a specific time?
    637639 *
    638  * @see WP_Query::is_time()
    639640 * @since 1.5.0
    640  * @uses $wp_query
     641 *
     642 * @global WP_Query $wp_query
    641643 *
    642644 * @return bool
     
    656658 * Is the query for a trackback endpoint call?
    657659 *
    658  * @see WP_Query::is_trackback()
    659660 * @since 1.5.0
    660  * @uses $wp_query
     661 *
     662 * @global WP_Query $wp_query
    661663 *
    662664 * @return bool
     
    676678 * Is the query for an existing year archive?
    677679 *
    678  * @see WP_Query::is_year()
    679680 * @since 1.5.0
    680  * @uses $wp_query
     681 *
     682 * @global WP_Query $wp_query
    681683 *
    682684 * @return bool
     
    696698 * Is the query a 404 (returns no results)?
    697699 *
    698  * @see WP_Query::is_404()
    699700 * @since 1.5.0
    700  * @uses $wp_query
     701 *
     702 * @global WP_Query $wp_query
    701703 *
    702704 * @return bool
     
    717719 *
    718720 * @since 3.3.0
     721 *
     722 * @global WP_Query $wp_query
    719723 *
    720724 * @return bool
     
    738742 * Whether current WordPress query has results to loop over.
    739743 *
    740  * @see WP_Query::have_posts()
    741744 * @since 1.5.0
    742  * @uses $wp_query
     745 *
     746 * @global WP_Query $wp_query
    743747 *
    744748 * @return bool
     
    746750function have_posts() {
    747751    global $wp_query;
    748 
    749752    return $wp_query->have_posts();
    750753}
     
    754757 *
    755758 * @since 2.0.0
    756  * @uses $wp_query
     759 *
     760 * @global WP_Query $wp_query
    757761 *
    758762 * @return bool True if caller is within loop, false if loop hasn't started or ended.
     
    760764function in_the_loop() {
    761765    global $wp_query;
    762 
    763766    return $wp_query->in_the_loop;
    764767}
     
    767770 * Rewind the loop posts.
    768771 *
    769  * @see WP_Query::rewind_posts()
    770772 * @since 1.5.0
    771  * @uses $wp_query
    772  *
    773  * @return null
     773 *
     774 * @global WP_Query $wp_query
    774775 */
    775776function rewind_posts() {
    776777    global $wp_query;
    777 
    778     return $wp_query->rewind_posts();
     778    $wp_query->rewind_posts();
    779779}
    780780
     
    782782 * Iterate the post index in the loop.
    783783 *
    784  * @see WP_Query::the_post()
    785784 * @since 1.5.0
    786  * @uses $wp_query
     785 *
     786 * @global WP_Query $wp_query
    787787 */
    788788function the_post() {
    789789    global $wp_query;
    790 
    791790    $wp_query->the_post();
    792791}
     
    799798 * Whether there are comments to loop over.
    800799 *
    801  * @see WP_Query::have_comments()
    802800 * @since 2.2.0
    803  * @uses $wp_query
     801 *
     802 * @global WP_Query $wp_query
    804803 *
    805804 * @return bool
     
    813812 * Iterate comment index in the comment loop.
    814813 *
    815  * @see WP_Query::the_comment()
    816814 * @since 2.2.0
    817  * @uses $wp_query
     815 *
     816 * @global WP_Query $wp_query
    818817 *
    819818 * @return object
     
    21802179     *
    21812180     * @global wpdb $wpdb
     2181     *
    21822182     * @param array $q Query variables.
    21832183     * @return string ORDER BY clause.
     
    22252225     *
    22262226     * @param string $orderby Alias for the field to order by.
    2227      * @return string|bool Table-prefixed value to used in the ORDER clause. False otherwise.
     2227     * @return string|false Table-prefixed value to used in the ORDER clause. False otherwise.
    22282228     */
    22292229    protected function parse_orderby( $orderby ) {
     
    23612361     *
    23622362     * @param string $query_var Query variable key.
    2363      * @param mixed $value Query variable value.
     2363     * @param mixed  $value    Query variable value.
    23642364     */
    23652365    public function set($query_var, $value) {
     
    23752375     * @since 1.5.0
    23762376     * @access public
     2377     *
     2378     * @global wpdb $wpdb
    23772379     *
    23782380     * @return array List of posts.
     
    36573659     * @since 3.5.0
    36583660     * @access private
     3661     *
     3662     * @global wpdb $wpdb
    36593663     */
    36603664    private function set_found_posts( $q, $limits ) {
     
    37183722     * @since 1.5.0
    37193723     * @access public
     3724     *
     3725     * @global WP_Post $post
    37203726     */
    37213727    public function the_post() {
     
    40154021     * @param callable $name      Method to call.
    40164022     * @param array    $arguments Arguments to pass when calling.
    4017      * @return mixed|bool Return value of the callback, false otherwise.
     4023     * @return mixed|false Return value of the callback, false otherwise.
    40184024     */
    40194025    public function __call( $name, $arguments ) {
     
    41954201     *
    41964202     * @since 3.1.0
     4203     *
     4204     * @global array $wp_taxonomies
    41974205     *
    41984206     * @param mixed $taxonomy Optional. Taxonomy slug or slugs.
     
    45574565     * @since 3.3.0
    45584566     *
     4567     * @global WP_Query $wp_query
     4568     *
    45594569     * @return bool
    45604570     */
     
    45694579     * @since 4.1.0
    45704580     *
     4581     * @global int             $id
     4582     * @global WP_User         $authordata
     4583     * @global string|int|bool $currentday
     4584     * @global string|int|bool $currentmonth
     4585     * @global int             $page
     4586     * @global array           $pages
     4587     * @global int             $multipage
     4588     * @global int             $more
     4589     * @global int             $numpages
     4590     *
    45714591     * @param WP_Post $post Post data.
    4572      * @return bool True when finished.
     4592     * @return true True when finished.
    45734593     */
    45744594    public function setup_postdata( $post ) {
     
    46374657     *
    46384658     * @since 3.7.0
     4659     *
     4660     * @global WP_Post $post
    46394661     */
    46404662    public function reset_postdata() {
     
    46534675 * @since 2.1.0
    46544676 *
    4655  * @uses $wp_query
    4656  * @global wpdb $wpdb WordPress database abstraction object.
    4657  *
    4658  * @return null If no link is found, null is returned.
     4677 * @global WP_Query $wp_query
     4678 * @global wpdb     $wpdb     WordPress database abstraction object.
    46594679 */
    46604680function wp_old_slug_redirect() {
     
    47124732 * @since 1.5.0
    47134733 *
     4734 * @global WP_Query $wp_query
     4735 *
    47144736 * @param object $post Post data.
    47154737 * @return bool True when finished.
Note: See TracChangeset for help on using the changeset viewer.