From 72d586206926fe6d4b9b88ceabd42d68b08b9bed Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 10 Jul 2020 20:21:01 +0000 Subject: [PATCH] Docs: Improve `@return` tags for various conditional tags. Props stevenlinx, SergeyBiryukov. Fixes #50626. git-svn-id: https://develop.svn.wordpress.org/trunk@48426 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-wp-query.php | 59 ++++++++++++++++-------------- src/wp-includes/deprecated.php | 2 +- src/wp-includes/query.php | 55 ++++++++++++++-------------- 3 files changed, 60 insertions(+), 56 deletions(-) diff --git a/src/wp-includes/class-wp-query.php b/src/wp-includes/class-wp-query.php index 4f9430ae92..da812c7bd3 100644 --- a/src/wp-includes/class-wp-query.php +++ b/src/wp-includes/class-wp-query.php @@ -3605,7 +3605,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for an existing archive page. */ public function is_archive() { return (bool) $this->is_archive; @@ -3618,7 +3618,7 @@ class WP_Query { * * @param string|string[] $post_types Optional. Post type or array of posts types * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing post type archive page. */ public function is_post_type_archive( $post_types = '' ) { if ( empty( $post_types ) || ! $this->is_post_type_archive ) { @@ -3641,7 +3641,7 @@ class WP_Query { * * @param int|string|int[]|string[] $attachment Optional. Attachment ID, title, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing attachment page. */ public function is_attachment( $attachment = '' ) { if ( ! $this->is_attachment ) { @@ -3676,7 +3676,7 @@ class WP_Query { * * @param int|string|int[]|string[] $author Optional. User ID, nickname, nicename, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing author archive page. */ public function is_author( $author = '' ) { if ( ! $this->is_author ) { @@ -3712,7 +3712,7 @@ class WP_Query { * * @param int|string|int[]|string[] $category Optional. Category ID, name, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing category archive page. */ public function is_category( $category = '' ) { if ( ! $this->is_category ) { @@ -3748,7 +3748,7 @@ class WP_Query { * * @param int|string|int[]|string[] $tag Optional. Tag ID, name, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing tag archive page. */ public function is_tag( $tag = '' ) { if ( ! $this->is_tag ) { @@ -3792,7 +3792,8 @@ class WP_Query { * Default empty. * @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such * to check against. Default empty. - * @return bool True for custom taxonomy archive pages, false for built-in taxonomies + * @return bool Whether the query is for an existing custom taxonomy archive page. + * True for custom taxonomy archive pages, false for built-in taxonomies * (category and tag archives). */ public function is_tax( $taxonomy = '', $term = '' ) { @@ -3835,7 +3836,7 @@ class WP_Query { * @since 3.1.0 * @deprecated 4.5.0 * - * @return bool + * @return false Always returns false. */ public function is_comments_popup() { _deprecated_function( __FUNCTION__, '4.5.0' ); @@ -3848,7 +3849,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for an existing date archive. */ public function is_date() { return (bool) $this->is_date; @@ -3859,7 +3860,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for an existing day archive. */ public function is_day() { return (bool) $this->is_day; @@ -3872,16 +3873,18 @@ class WP_Query { * * @param string|string[] $feeds Optional. Feed type or array of feed types * to check against. Default empty. - * @return bool + * @return bool Whether the query is for a feed. */ public function is_feed( $feeds = '' ) { if ( empty( $feeds ) || ! $this->is_feed ) { return (bool) $this->is_feed; } + $qv = $this->get( 'feed' ); if ( 'feed' === $qv ) { $qv = get_default_feed(); } + return in_array( $qv, (array) $feeds, true ); } @@ -3890,7 +3893,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a comments feed. */ public function is_comment_feed() { return (bool) $this->is_comment_feed; @@ -3910,7 +3913,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool True, if front of site. + * @return bool Whether the query is for the front page of the site. */ public function is_front_page() { // Most likely case. @@ -3939,7 +3942,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool True if blog view homepage. + * @return bool Whether the query is for the blog homepage. */ public function is_home() { return (bool) $this->is_home; @@ -3956,7 +3959,7 @@ class WP_Query { * * @since 5.2.0 * - * @return bool True, if Privacy Policy page. + * @return bool Whether the query is for the Privacy Policy page. */ public function is_privacy_policy() { if ( get_option( 'wp_page_for_privacy_policy' ) @@ -3973,7 +3976,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for an existing month archive. */ public function is_month() { return (bool) $this->is_month; @@ -4030,11 +4033,11 @@ class WP_Query { } /** - * Is the query for paged result and not for the first page? + * Is the query for a paged result and not for the first page? * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a paged result. */ public function is_paged() { return (bool) $this->is_paged; @@ -4045,7 +4048,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a post or page preview. */ public function is_preview() { return (bool) $this->is_preview; @@ -4056,7 +4059,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for the robots.txt file. */ public function is_robots() { return (bool) $this->is_robots; @@ -4067,7 +4070,7 @@ class WP_Query { * * @since 5.4.0 * - * @return bool + * @return bool Whether the query is for the favicon.ico file. */ public function is_favicon() { return (bool) $this->is_favicon; @@ -4078,7 +4081,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a search. */ public function is_search() { return (bool) $this->is_search; @@ -4167,7 +4170,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a specific time. */ public function is_time() { return (bool) $this->is_time; @@ -4178,7 +4181,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for a trackback endpoint call. */ public function is_trackback() { return (bool) $this->is_trackback; @@ -4189,7 +4192,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is for an existing year archive. */ public function is_year() { return (bool) $this->is_year; @@ -4200,7 +4203,7 @@ class WP_Query { * * @since 3.1.0 * - * @return bool + * @return bool Whether the query is a 404 error. */ public function is_404() { return (bool) $this->is_404; @@ -4211,7 +4214,7 @@ class WP_Query { * * @since 4.4.0 * - * @return bool + * @return bool Whether the query is for an embedded post. */ public function is_embed() { return (bool) $this->is_embed; @@ -4224,7 +4227,7 @@ class WP_Query { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is the main query. */ public function is_main_query() { global $wp_the_query; diff --git a/src/wp-includes/deprecated.php b/src/wp-includes/deprecated.php index 06f28a42aa..43450e8d4a 100644 --- a/src/wp-includes/deprecated.php +++ b/src/wp-includes/deprecated.php @@ -3749,7 +3749,7 @@ function get_comments_popup_template() { * @since 1.5.0 * @deprecated 4.5.0 * - * @return bool + * @return false Always returns false. */ function is_comments_popup() { _deprecated_function( __FUNCTION__, '4.5.0' ); diff --git a/src/wp-includes/query.php b/src/wp-includes/query.php index 743a33df80..780c5d3e3e 100644 --- a/src/wp-includes/query.php +++ b/src/wp-includes/query.php @@ -148,7 +148,7 @@ function wp_reset_postdata() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for an existing archive page. */ function is_archive() { global $wp_query; @@ -174,7 +174,7 @@ function is_archive() { * * @param string|string[] $post_types Optional. Post type or array of posts types * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing post type archive page. */ function is_post_type_archive( $post_types = '' ) { global $wp_query; @@ -200,7 +200,7 @@ function is_post_type_archive( $post_types = '' ) { * * @param int|string|int[]|string[] $attachment Optional. Attachment ID, title, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing attachment page. */ function is_attachment( $attachment = '' ) { global $wp_query; @@ -229,7 +229,7 @@ function is_attachment( $attachment = '' ) { * * @param int|string|int[]|string[] $author Optional. User ID, nickname, nicename, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing author archive page. */ function is_author( $author = '' ) { global $wp_query; @@ -258,7 +258,7 @@ function is_author( $author = '' ) { * * @param int|string|int[]|string[] $category Optional. Category ID, name, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing category archive page. */ function is_category( $category = '' ) { global $wp_query; @@ -287,7 +287,7 @@ function is_category( $category = '' ) { * * @param int|string|int[]|string[] $tag Optional. Tag ID, name, slug, or array of such * to check against. Default empty. - * @return bool + * @return bool Whether the query is for an existing tag archive page. */ function is_tag( $tag = '' ) { global $wp_query; @@ -322,7 +322,8 @@ function is_tag( $tag = '' ) { * Default empty. * @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such * to check against. Default empty. - * @return bool True for custom taxonomy archive pages, false for built-in taxonomies + * @return bool Whether the query is for an existing custom taxonomy archive page. + * True for custom taxonomy archive pages, false for built-in taxonomies * (category and tag archives). */ function is_tax( $taxonomy = '', $term = '' ) { @@ -347,7 +348,7 @@ function is_tax( $taxonomy = '', $term = '' ) { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for an existing date archive. */ function is_date() { global $wp_query; @@ -373,7 +374,7 @@ function is_date() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for an existing day archive. */ function is_day() { global $wp_query; @@ -399,7 +400,7 @@ function is_day() { * * @param string|string[] $feeds Optional. Feed type or array of feed types * to check against. Default empty. - * @return bool + * @return bool Whether the query is for a feed. */ function is_feed( $feeds = '' ) { global $wp_query; @@ -419,7 +420,7 @@ function is_feed( $feeds = '' ) { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a comments feed. */ function is_comment_feed() { global $wp_query; @@ -452,7 +453,7 @@ function is_comment_feed() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool True, if front of site. + * @return bool Whether the query is for the front page of the site. */ function is_front_page() { global $wp_query; @@ -485,7 +486,7 @@ function is_front_page() { * @see is_front_page() * @global WP_Query $wp_query WordPress Query object. * - * @return bool True if blog view homepage, otherwise false. + * @return bool Whether the query is for the blog homepage. */ function is_home() { global $wp_query; @@ -515,7 +516,7 @@ function is_home() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for the Privacy Policy page. */ function is_privacy_policy() { global $wp_query; @@ -539,7 +540,7 @@ function is_privacy_policy() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for an existing month archive. */ function is_month() { global $wp_query; @@ -585,7 +586,7 @@ function is_page( $page = '' ) { } /** - * Determines whether the query is for paged results and not for the first page. + * Determines whether the query is for a paged result and not for the first page. * * For more information on this and similar theme functions, check out * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ @@ -595,7 +596,7 @@ function is_page( $page = '' ) { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a paged result. */ function is_paged() { global $wp_query; @@ -619,7 +620,7 @@ function is_paged() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a post or page preview. */ function is_preview() { global $wp_query; @@ -639,7 +640,7 @@ function is_preview() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for the robots.txt file. */ function is_robots() { global $wp_query; @@ -659,7 +660,7 @@ function is_robots() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for the favicon.ico file. */ function is_favicon() { global $wp_query; @@ -683,7 +684,7 @@ function is_favicon() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a search. */ function is_search() { global $wp_query; @@ -775,7 +776,7 @@ function is_singular( $post_types = '' ) { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a specific time. */ function is_time() { global $wp_query; @@ -799,7 +800,7 @@ function is_time() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for a trackback endpoint call. */ function is_trackback() { global $wp_query; @@ -823,7 +824,7 @@ function is_trackback() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is for an existing year archive. */ function is_year() { global $wp_query; @@ -847,7 +848,7 @@ function is_year() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is a 404 error. */ function is_404() { global $wp_query; @@ -867,7 +868,7 @@ function is_404() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool Whether we're in an embedded post or not. + * @return bool Whether the query is for an embedded post. */ function is_embed() { global $wp_query; @@ -891,7 +892,7 @@ function is_embed() { * * @global WP_Query $wp_query WordPress Query object. * - * @return bool + * @return bool Whether the query is the main query. */ function is_main_query() { if ( 'pre_get_posts' === current_filter() ) {