Link to the Conditional Tags article in the themes handbook from DocBlocks for all conditional tag functions

[DrewAPicture]

We have a lot of conditional tags in core. And by virtue of being conditional, they're therefore all related.

We've recently had some contributions to the Code Reference from @ahortin attempting to link those functions together via "Related" lists, and since we've already codified a fancy document about them in the themes handbook, we should just point interested parties there for more information instead of posting giant link lists on DevHub.

I would suggest we link the page in the DocBlock descriptions via an inline @link tag vs a standalone one (which currently isn't exposed anywhere when the Code Reference is parsed from source). Inline link tags use the following syntax: {@link URL Label}

I'd propose we use the same standard language along the lines of this:

For more information on this and similar theme functions, check out the [Conditional Tags] article in the Theme Developer Handbook.

The handbook article: ​https://developer.wordpress.org/themes/basics/conditional-tags/

The conditional tags whose docs should reference it:

• comments_open()
• is_404()
• is_admin()
• is_admin_bar_showing()
• is_archive()
• is_attachment()
• is_author()
• is_category()
• is_comments_popup()
• is_date()
• is_day()
• is_feed()
• is_front_page()
• is_home()
• is_local_attachment()
• is_main_query
• is_multi_author
• is_month()
• 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_search()
• is_single()
• is_singular()
• is_sticky()
• is_tag()
• is_tax()
• is_taxonomy_hierarchical()
• is_time()
• is_trackback()
• is_year()
• in_category()
• in_the_loop()
• is_active_sidebar()
• is_active_widget()
• is_blog_installed()
• is_rtl()
• is_dynamic_sidebar()
• is_user_logged_in()
• has_excerpt()
• has_post_thumbnail()
• has_tag()
• pings_open()
• email exists()
• post_type_exists()
• taxonomy_exists()
• term_exists()
• username exists()
• wp_attachment_is_image()
• wp_script_is()

[flixos90]

Marking the ticket as claimed, per WordCamp Noord contributor day.

[janalwin]

Added the link ​https://developer.wordpress.org/themes/basics/conditional-tags/ to dockblock descriptions of the functions mentioned above.

[DrewAPicture]

Hi @janalwin, thanks for the patch.

I think there may have been a disconnect in how you understood the task description. Your patch uses standalone @link tags, which aren't exposed in the Code Reference. The main reason for using an inline @link tag is so that we can expose in the function descriptions on the Code Reference for each of these functions.

In short, your patch proposes something like this:

file.php

@@ -463 @@
- *
+ * 
+ * @link https://developer.wordpress.org/themes/basics/conditional-tags/
+ * 

When I was expecting something more like this:

file.php

@@ -463 @@
- *
+ * 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.
+ *

Would you like to update your patch to use inline @link tags instead?

[janalwin]

Hi @DrewAPicture,

I implemented the changes you asked for.

Hope it's allright this time.

First time is always difficult :-)

[DrewAPicture]

In 42710:

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.

[DrewAPicture]

Hi @janalwin, yep everything is great here, thanks for the effort! This is ticket is all done :-)

[DrewAPicture]

@pento Any chance we get this in 5.0? The @link notations added here were added for the benefit of the Code Reference because we keep seeing people trying to contribute "Related Functions" notes for these functions.

[pento]

Yah, this is fine to include in 5.0.

[DrewAPicture]

In 43827:

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 have 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()

Merges [42710] to the 5.0 branch.

Props janalwin.
Fixes #43254.