Docs: Link to the "Conditional Tags" article in the Theme Developer Handbook from the descriptions for a variety of core conditional tag functions.

These notations largely serve to direct consumers (of both the source and the parsed code reference) to extended information on individual and related conditional tags throughout WordPress. The changeset also standardizes corresponding DocBlock summaries to use third-person singular verbs.

Notations been added for the following functions:

* comments_open()
* email exists()
* has_excerpt()
* has_post_thumbnail()
* has_tag()
* in_category()
* in_the_loop()
* is_404()
* is_active_sidebar()
* is_active_widget()
* is_admin()
* is_admin_bar_showing()
* is_archive()
* is_attachment()
* is_author()
* is_blog_installed()
* is_category()
* is_comments_popup()
* is_date()
* is_day()
* is_dynamic_sidebar()
* is_feed()
* is_front_page()
* is_home()
* is_local_attachment()
* is_main_query
* is_month()
* is_multi_author
* is_new_day()
* is_page()
* is_page_template()
* is_paged()
* is_plugin_active()
* is_plugin_active_for_network()
* is_plugin_inactive()
* is_plugin_page()
* is_post_type_archive()
* is_preview()
* is_rtl()
* is_search()
* is_single()
* is_singular()
* is_sticky()
* is_tag()
* is_tax()
* is_taxonomy_hierarchical()
* is_time()
* is_trackback()
* is_user_logged_in()
* is_year()
* pings_open()
* post_type_exists()
* taxonomy_exists()
* term_exists()
* username exists()
* wp_attachment_is_image()
* wp_script_is()

Props janalwin.
Fixes #43254.

Built from https://develop.svn.wordpress.org/trunk@42710


git-svn-id: http://core.svn.wordpress.org/trunk@42538 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/query.php

@@ -136,10 +136,14 @@ function wp_reset_postdata() {
  */
 
 /**
- * Is the query for an existing archive page?
+ * Determines whether the query is for an existing archive page.
  *
  * Month, Year, Category, Author, Post Type archive...
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -158,8 +162,12 @@ function is_archive() {
 }
 
 /**
- * Is the query for an existing post type archive page?
- *
+ * Determines whether the query is for an existing post type archive page.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 3.1.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -179,8 +187,12 @@ function is_post_type_archive( $post_types = '' ) {
 }
 
 /**
- * Is the query for an existing attachment page?
- *
+ * Determines whether the query is for an existing attachment page.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 2.0.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -200,11 +212,15 @@ function is_attachment( $attachment = '' ) {
 }
 
 /**
- * Is the query for an existing author archive page?
+ * Determines whether the query is for an existing author archive page.
  *
  * If the $author parameter is specified, this function will additionally
  * check if the query is for one of the authors specified.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -224,11 +240,15 @@ function is_author( $author = '' ) {
 }
 
 /**
- * Is the query for an existing category archive page?
+ * Determines whether the query is for an existing category archive page.
  *
  * If the $category parameter is specified, this function will additionally
  * check if the query is for one of the categories specified.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -248,10 +268,14 @@ function is_category( $category = '' ) {
 }
 
 /**
- * Is the query for an existing tag archive page?
+ * Determines whether the query is for an existing tag archive page.
  *
  * If the $tag parameter is specified, this function will additionally
  * check if the query is for one of the tags specified.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 2.3.0
  *
@@ -272,7 +296,7 @@ function is_tag( $tag = '' ) {
 }
 
 /**
- * Is the query for an existing custom taxonomy archive page?
+ * Determines whether the query is for an existing custom taxonomy archive page.
  *
  * If the $taxonomy parameter is specified, this function will additionally
  * check if the query is for that specific $taxonomy.
@@ -280,6 +304,10 @@ function is_tag( $tag = '' ) {
  * If the $term parameter is specified in addition to the $taxonomy parameter,
  * this function will additionally check if the query is for one of the terms
  * specified.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 2.5.0
  *
@@ -301,8 +329,12 @@ function is_tax( $taxonomy = '', $term = '' ) {
 }
 
 /**
- * Is the query for an existing date archive?
- *
+ * Determines whether the query is for an existing date archive.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -321,10 +353,14 @@ function is_date() {
 }
 
 /**
- * Is the query for an existing day archive?
+ * Determines whether the query is for an existing day archive.
  *
  * A conditional check to test whether the page is a date-based archive page displaying posts for the current day.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -343,8 +379,12 @@ function is_day() {
 }
 
 /**
- * Is the query for a feed?
- *
+ * Determines whether the query is for a feed.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -384,7 +424,7 @@ function is_comment_feed() {
 }
 
 /**
- * Is the query for the front page of the site?
+ * Determines whether the query is for the front page of the site.
  *
  * This is for what is displayed at your site's main URL.
  *
@@ -394,7 +434,11 @@ function is_comment_feed() {
  * true when viewing that page.
  *
  * Otherwise the same as @see is_home()
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 2.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -413,7 +457,7 @@ function is_front_page() {
 }
 
 /**
- * Determines if the query is for the blog homepage.
+ * Determines whether the query is for the blog homepage.
  *
  * The blog homepage is the page that shows the time-based blog content of the site.
  *
@@ -422,7 +466,11 @@ function is_front_page() {
  *
  * If a static page is set for the front page of the site, this function will return true only
  * on the page you set as the "Posts page".
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @see is_front_page()
@@ -442,8 +490,12 @@ function is_home() {
 }
 
 /**
- * Is the query for an existing month archive?
- *
+ * Determines whether the query is for an existing month archive.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -462,11 +514,15 @@ function is_month() {
 }
 
 /**
- * Is the query for an existing single page?
+ * Determines whether the query is for an existing single page.
  *
  * If the $page parameter is specified, this function will additionally
  * check if the query is for one of the pages specified.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @see is_single()
  * @see is_singular()
  *
@@ -489,8 +545,12 @@ function is_page( $page = '' ) {
 }
 
 /**
- * Is the query for paged result and not for the first page?
- *
+ * Determines whether the query is for paged results 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/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -509,8 +569,12 @@ function is_paged() {
 }
 
 /**
- * Is the query for a post or page preview?
- *
+ * Determines whether the query is for a post or page preview.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 2.0.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -549,8 +613,12 @@ function is_robots() {
 }
 
 /**
- * Is the query for a search?
- *
+ * Determines whether the query is for a search.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -569,13 +637,17 @@ function is_search() {
 }
 
 /**
- * Is the query for an existing single post?
+ * Determines whether the query is for an existing single post.
  *
  * Works for any post type, except attachments and pages
  *
  * If the $post parameter is specified, this function will additionally
  * check if the query is for one of the Posts specified.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @see is_page()
  * @see is_singular()
  *
@@ -598,12 +670,16 @@ function is_single( $post = '' ) {
 }
 
 /**
- * Is the query for an existing single post of any post type (post, attachment, page,
- * custom post types)?
+ * Determines whether the query is for an existing single post of any post type
+ * (post, attachment, page, custom post types).
  *
  * If the $post_types parameter is specified, this function will additionally
  * check if the query is for one of the Posts Types specified.
- *
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @see is_page()
  * @see is_single()
  *
@@ -626,7 +702,11 @@ function is_singular( $post_types = '' ) {
 }
 
 /**
- * Is the query for a specific time?
+ * Determines whether the query is for a specific time.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 1.5.0
  *
@@ -646,7 +726,11 @@ function is_time() {
 }
 
 /**
- * Is the query for a trackback endpoint call?
+ * Determines whether the query is for a trackback endpoint call.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 1.5.0
  *
@@ -666,7 +750,11 @@ function is_trackback() {
 }
 
 /**
- * Is the query for an existing year archive?
+ * Determines whether the query is for an existing year archive.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 1.5.0
  *
@@ -686,8 +774,12 @@ function is_year() {
 }
 
 /**
- * Is the query a 404 (returns no results)?
- *
+ * Determines whether the query has resulted in a 404 (returns no results).
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 1.5.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -726,8 +818,12 @@ function is_embed() {
 }
 
 /**
- * Is the query the main query?
- *
+ * Determines whether the query is the main query.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
+ * 
  * @since 3.3.0
  *
  * @global WP_Query $wp_query Global WP_Query instance.
@@ -770,7 +866,11 @@ function have_posts() {
 }
 
 /**
- * Whether the caller is in the Loop.
+ * Determines whether the caller is in the Loop.
+ * 
+ * For more information on this and similar theme functions, check out
+ * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 
+ * Conditional Tags} article in the Theme Developer Handbook.
  *
  * @since 2.0.0
  *