WordPress.org

Make WordPress Core

Opened 2 weeks ago

Closed 10 days ago

Last modified 10 days ago

#43254 closed task (blessed) (fixed)

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

Reported by: DrewAPicture Owned by: janalwin
Milestone: 5.0 Priority: normal
Severity: normal Version:
Component: Themes Keywords: good-first-bug has-patch
Focuses: docs Cc:

Description (last modified by 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()

Attachments (2)

43254.diff (18.2 KB) - added by janalwin 2 weeks ago.
43254.2.diff (26.2 KB) - added by janalwin 11 days ago.

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
2 weeks ago

  • Description modified (diff)

#2 @flixos90
2 weeks ago

  • Owner set to janalwin
  • Status changed from new to assigned

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

@janalwin
2 weeks ago

#3 @janalwin
2 weeks ago

  • Keywords has-patch added; needs-patch removed

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

#4 @DrewAPicture
2 weeks ago

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  * 
     463 *  
     464 * @link https://developer.wordpress.org/themes/basics/conditional-tags/ 
     465 *  

When I was expecting something more like this:

  • file.php

     
    463  * 
     463 * For more information on this and similar theme functions, check out the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ Conditional Tags} 
     464 * article in the Theme Developer Handbook. 
     465 * 

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

@janalwin
11 days ago

#5 @janalwin
11 days ago

Hi @DrewAPicture,

I implemented the changes you asked for.

Hope it's allright this time.

First time is always difficult :-)

#6 @DrewAPicture
10 days ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#7 @DrewAPicture
10 days ago

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

Note: See TracTickets for help on using tickets.