Make WordPress Core

Opened 6 years ago

Closed 6 years ago

Last modified 6 years 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's profile DrewAPicture Owned by: janalwin's profile 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 6 years ago.
43254.2.diff (26.2 KB) - added by janalwin 6 years ago.

Download all attachments as: .zip

Change History (14)

#1 @DrewAPicture
6 years ago

  • Description modified (diff)

#2 @flixos90
6 years ago

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

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

@janalwin
6 years ago

#3 @janalwin
6 years 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
6 years 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
6 years ago

#5 @janalwin
6 years ago

Hi @DrewAPicture,

I implemented the changes you asked for.

Hope it's allright this time.

First time is always difficult :-)

#6 @DrewAPicture
6 years 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
6 years ago

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

#8 @johnbillion
6 years ago

  • Milestone changed from 5.0 to 5.1

#9 @DrewAPicture
6 years ago

@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.

#10 @pento
6 years ago

  • Milestone changed from 5.1 to 5.0
  • Resolution fixed deleted
  • Status changed from closed to reopened

Yah, this is fine to include in 5.0.

#11 @DrewAPicture
6 years ago

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

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.

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.


6 years ago

Note: See TracTickets for help on using tickets.