sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: Improve @return tags for various conditional tags.

Browse Source 
Props stevenlinx, SergeyBiryukov.
Fixes #50626.

git-svn-id: https://develop.svn.wordpress.org/trunk@48426 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-07-10 20:21:01 +00:00
parent a7a91ba8dc
commit 72d5862069
3 changed files with 60 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
src/wp-includes/class-wp-query.php
View File

@ -3605,7 +3605,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for an existing archive page.
*/ */
public function is_archive() { public function is_archive() {
return (bool) $this->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 * @param string|string[] $post_types Optional. Post type or array of posts types
* to check against. Default empty. * 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 = '' ) { public function is_post_type_archive( $post_types = '' ) {
if ( empty( $post_types ) || ! $this->is_post_type_archive ) { 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 * @param int|string|int[]|string[] $attachment Optional. Attachment ID, title, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing attachment page.
*/ */
public function is_attachment( $attachment = '' ) { public function is_attachment( $attachment = '' ) {
if ( ! $this->is_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 * @param int|string|int[]|string[] $author Optional. User ID, nickname, nicename, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing author archive page.
*/ */
public function is_author( $author = '' ) { public function is_author( $author = '' ) {
if ( ! $this->is_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 * @param int|string|int[]|string[] $category Optional. Category ID, name, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing category archive page.
*/ */
public function is_category( $category = '' ) { public function is_category( $category = '' ) {
if ( ! $this->is_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 * @param int|string|int[]|string[] $tag Optional. Tag ID, name, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing tag archive page.
*/ */
public function is_tag( $tag = '' ) { public function is_tag( $tag = '' ) {
if ( ! $this->is_tag ) { if ( ! $this->is_tag ) {
@ -3792,7 +3792,8 @@ class WP_Query {
* Default empty. * Default empty.
* @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such * @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such
* to check against. Default empty. * 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). * (category and tag archives).
*/ */
public function is_tax( $taxonomy = '', $term = '' ) { public function is_tax( $taxonomy = '', $term = '' ) {
@ -3835,7 +3836,7 @@ class WP_Query {
* @since 3.1.0 * @since 3.1.0
* @deprecated 4.5.0 * @deprecated 4.5.0
* *
* @return bool * @return false Always returns false.
*/ */
public function is_comments_popup() { public function is_comments_popup() {
_deprecated_function( __FUNCTION__, '4.5.0' ); _deprecated_function( __FUNCTION__, '4.5.0' );
@ -3848,7 +3849,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for an existing date archive.
*/ */
public function is_date() { public function is_date() {
return (bool) $this->is_date; return (bool) $this->is_date;
@ -3859,7 +3860,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for an existing day archive.
*/ */
public function is_day() { public function is_day() {
return (bool) $this->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 * @param string|string[] $feeds Optional. Feed type or array of feed types
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for a feed.
*/ */
public function is_feed( $feeds = '' ) { public function is_feed( $feeds = '' ) {
if ( empty( $feeds ) || ! $this->is_feed ) { if ( empty( $feeds ) || ! $this->is_feed ) {
return (bool) $this->is_feed; return (bool) $this->is_feed;
} }
$qv = $this->get( 'feed' ); $qv = $this->get( 'feed' );
if ( 'feed' === $qv ) { if ( 'feed' === $qv ) {
$qv = get_default_feed(); $qv = get_default_feed();
} }
return in_array( $qv, (array) $feeds, true ); return in_array( $qv, (array) $feeds, true );
} }
@ -3890,7 +3893,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a comments feed.
*/ */
public function is_comment_feed() { public function is_comment_feed() {
return (bool) $this->is_comment_feed; return (bool) $this->is_comment_feed;
@ -3910,7 +3913,7 @@ class WP_Query {
* *
* @since 3.1.0 * @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() { public function is_front_page() {
// Most likely case. // Most likely case.
@ -3939,7 +3942,7 @@ class WP_Query {
* *
* @since 3.1.0 * @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() { public function is_home() {
return (bool) $this->is_home; return (bool) $this->is_home;
@ -3956,7 +3959,7 @@ class WP_Query {
* *
* @since 5.2.0 * @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() { public function is_privacy_policy() {
if ( get_option( 'wp_page_for_privacy_policy' ) if ( get_option( 'wp_page_for_privacy_policy' )
@ -3973,7 +3976,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for an existing month archive.
*/ */
public function is_month() { public function is_month() {
return (bool) $this->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 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a paged result.
*/ */
public function is_paged() { public function is_paged() {
return (bool) $this->is_paged; return (bool) $this->is_paged;
@ -4045,7 +4048,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a post or page preview.
*/ */
public function is_preview() { public function is_preview() {
return (bool) $this->is_preview; return (bool) $this->is_preview;
@ -4056,7 +4059,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for the robots.txt file.
*/ */
public function is_robots() { public function is_robots() {
return (bool) $this->is_robots; return (bool) $this->is_robots;
@ -4067,7 +4070,7 @@ class WP_Query {
* *
* @since 5.4.0 * @since 5.4.0
* *
* @return bool * @return bool Whether the query is for the favicon.ico file.
*/ */
public function is_favicon() { public function is_favicon() {
return (bool) $this->is_favicon; return (bool) $this->is_favicon;
@ -4078,7 +4081,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a search.
*/ */
public function is_search() { public function is_search() {
return (bool) $this->is_search; return (bool) $this->is_search;
@ -4167,7 +4170,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a specific time.
*/ */
public function is_time() { public function is_time() {
return (bool) $this->is_time; return (bool) $this->is_time;
@ -4178,7 +4181,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for a trackback endpoint call.
*/ */
public function is_trackback() { public function is_trackback() {
return (bool) $this->is_trackback; return (bool) $this->is_trackback;
@ -4189,7 +4192,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is for an existing year archive.
*/ */
public function is_year() { public function is_year() {
return (bool) $this->is_year; return (bool) $this->is_year;
@ -4200,7 +4203,7 @@ class WP_Query {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @return bool * @return bool Whether the query is a 404 error.
*/ */
public function is_404() { public function is_404() {
return (bool) $this->is_404; return (bool) $this->is_404;
@ -4211,7 +4214,7 @@ class WP_Query {
* *
* @since 4.4.0 * @since 4.4.0
* *
* @return bool * @return bool Whether the query is for an embedded post.
*/ */
public function is_embed() { public function is_embed() {
return (bool) $this->is_embed; return (bool) $this->is_embed;
@ -4224,7 +4227,7 @@ class WP_Query {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is the main query.
*/ */
public function is_main_query() { public function is_main_query() {
global $wp_the_query; global $wp_the_query;

2
src/wp-includes/deprecated.php
View File

@ -3749,7 +3749,7 @@ function get_comments_popup_template() {
* @since 1.5.0 * @since 1.5.0
* @deprecated 4.5.0 * @deprecated 4.5.0
* *
* @return bool * @return false Always returns false.
*/ */
function is_comments_popup() { function is_comments_popup() {
_deprecated_function( __FUNCTION__, '4.5.0' ); _deprecated_function( __FUNCTION__, '4.5.0' );

55
src/wp-includes/query.php
View File

@ -148,7 +148,7 @@ function wp_reset_postdata() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for an existing archive page.
*/ */
function is_archive() { function is_archive() {
global $wp_query; global $wp_query;
@ -174,7 +174,7 @@ function is_archive() {
* *
* @param string|string[] $post_types Optional. Post type or array of posts types * @param string|string[] $post_types Optional. Post type or array of posts types
* to check against. Default empty. * 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 = '' ) { function is_post_type_archive( $post_types = '' ) {
global $wp_query; 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 * @param int|string|int[]|string[] $attachment Optional. Attachment ID, title, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing attachment page.
*/ */
function is_attachment( $attachment = '' ) { function is_attachment( $attachment = '' ) {
global $wp_query; 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 * @param int|string|int[]|string[] $author Optional. User ID, nickname, nicename, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing author archive page.
*/ */
function is_author( $author = '' ) { function is_author( $author = '' ) {
global $wp_query; 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 * @param int|string|int[]|string[] $category Optional. Category ID, name, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing category archive page.
*/ */
function is_category( $category = '' ) { function is_category( $category = '' ) {
global $wp_query; 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 * @param int|string|int[]|string[] $tag Optional. Tag ID, name, slug, or array of such
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for an existing tag archive page.
*/ */
function is_tag( $tag = '' ) { function is_tag( $tag = '' ) {
global $wp_query; global $wp_query;
@ -322,7 +322,8 @@ function is_tag( $tag = '' ) {
* Default empty. * Default empty.
* @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such * @param int|string|int[]|string[] $term Optional. Term ID, name, slug, or array of such
* to check against. Default empty. * 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). * (category and tag archives).
*/ */
function is_tax( $taxonomy = '', $term = '' ) { function is_tax( $taxonomy = '', $term = '' ) {
@ -347,7 +348,7 @@ function is_tax( $taxonomy = '', $term = '' ) {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for an existing date archive.
*/ */
function is_date() { function is_date() {
global $wp_query; global $wp_query;
@ -373,7 +374,7 @@ function is_date() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for an existing day archive.
*/ */
function is_day() { function is_day() {
global $wp_query; global $wp_query;
@ -399,7 +400,7 @@ function is_day() {
* *
* @param string|string[] $feeds Optional. Feed type or array of feed types * @param string|string[] $feeds Optional. Feed type or array of feed types
* to check against. Default empty. * to check against. Default empty.
* @return bool * @return bool Whether the query is for a feed.
*/ */
function is_feed( $feeds = '' ) { function is_feed( $feeds = '' ) {
global $wp_query; global $wp_query;
@ -419,7 +420,7 @@ function is_feed( $feeds = '' ) {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for a comments feed.
*/ */
function is_comment_feed() { function is_comment_feed() {
global $wp_query; global $wp_query;
@ -452,7 +453,7 @@ function is_comment_feed() {
* *
* @global WP_Query $wp_query WordPress Query object. * @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() { function is_front_page() {
global $wp_query; global $wp_query;
@ -485,7 +486,7 @@ function is_front_page() {
* @see is_front_page() * @see is_front_page()
* @global WP_Query $wp_query WordPress Query object. * @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() { function is_home() {
global $wp_query; global $wp_query;
@ -515,7 +516,7 @@ function is_home() {
* *
* @global WP_Query $wp_query WordPress Query object. * @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() { function is_privacy_policy() {
global $wp_query; global $wp_query;
@ -539,7 +540,7 @@ function is_privacy_policy() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for an existing month archive.
*/ */
function is_month() { function is_month() {
global $wp_query; 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 * For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ * 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. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for a paged result.
*/ */
function is_paged() { function is_paged() {
global $wp_query; global $wp_query;
@ -619,7 +620,7 @@ function is_paged() {
* *
* @global WP_Query $wp_query WordPress Query object. * @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() { function is_preview() {
global $wp_query; global $wp_query;
@ -639,7 +640,7 @@ function is_preview() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for the robots.txt file.
*/ */
function is_robots() { function is_robots() {
global $wp_query; global $wp_query;
@ -659,7 +660,7 @@ function is_robots() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for the favicon.ico file.
*/ */
function is_favicon() { function is_favicon() {
global $wp_query; global $wp_query;
@ -683,7 +684,7 @@ function is_favicon() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for a search.
*/ */
function is_search() { function is_search() {
global $wp_query; global $wp_query;
@ -775,7 +776,7 @@ function is_singular( $post_types = '' ) {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for a specific time.
*/ */
function is_time() { function is_time() {
global $wp_query; global $wp_query;
@ -799,7 +800,7 @@ function is_time() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for a trackback endpoint call.
*/ */
function is_trackback() { function is_trackback() {
global $wp_query; global $wp_query;
@ -823,7 +824,7 @@ function is_trackback() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is for an existing year archive.
*/ */
function is_year() { function is_year() {
global $wp_query; global $wp_query;
@ -847,7 +848,7 @@ function is_year() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is a 404 error.
*/ */
function is_404() { function is_404() {
global $wp_query; global $wp_query;
@ -867,7 +868,7 @@ function is_404() {
* *
* @global WP_Query $wp_query WordPress Query object. * @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() { function is_embed() {
global $wp_query; global $wp_query;
@ -891,7 +892,7 @@ function is_embed() {
* *
* @global WP_Query $wp_query WordPress Query object. * @global WP_Query $wp_query WordPress Query object.
* *
* @return bool * @return bool Whether the query is the main query.
*/ */
function is_main_query() { function is_main_query() {
if ( 'pre_get_posts' === current_filter() ) { if ( 'pre_get_posts' === current_filter() ) {