WordPress.org

Make WordPress Core

Opened 4 months ago

Closed 3 months ago

Last modified 3 months 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 4 months ago.
43254.2.diff (26.2 KB) - added by janalwin 3 months ago.

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
4 months ago

  • Description modified (diff)

#2 @flixos90
4 months ago

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

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

@janalwin
4 months ago

#3 @janalwin
4 months 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
4 months 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
3 months ago

#5 @janalwin
3 months ago

Hi @DrewAPicture,

I implemented the changes you asked for.

Hope it's allright this time.

First time is always difficult :-)

#6 @DrewAPicture
3 months 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
3 months 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.