WordPress.org

Make WordPress Core

Opened 17 months ago

Closed 17 months ago

Last modified 15 months ago

#26742 closed defect (bug) (fixed)

Improve inline docs for get_*_template() functions

Reported by: UmeshSingla Owned by: DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version: 3.8
Component: Themes Keywords: has-patch commit
Focuses: docs, template Cc:

Description

Description for get_taxonomy_template() function in template.php states that it uses 'template_taxonomy' filter which is seen nowhere in the function

@since 2.5.0

  • @uses apply_filters() Calls 'taxonomy_template' filter on found path.


Attachments (6)

template.diff (11.7 KB) - added by UmeshSingla 17 months ago.
removed unwanted description lines for get_taxonomy_template() function
template.php.patch (480 bytes) - added by UmeshSingla 17 months ago.
Patch File
template.php.2.patch (774 bytes) - added by UmeshSingla 17 months ago.
Updated description for get_query_template(), as the filter is being applied here in actual
26742.patch (2.0 KB) - added by SergeyBiryukov 17 months ago.
26742.2.patch (4.3 KB) - added by SergeyBiryukov 17 months ago.
26742.3.patch (7.7 KB) - added by DrewAPicture 17 months ago.
@see + returns + alternative filter description

Download all attachments as: .zip

Change History (18)

@UmeshSingla17 months ago

removed unwanted description lines for get_taxonomy_template() function

@UmeshSingla17 months ago

Patch File

@UmeshSingla17 months ago

Updated description for get_query_template(), as the filter is being applied here in actual

comment:1 @UmeshSingla17 months ago

get_taxonomy_template(), get_tag_template(), get_category_template() all uses get_query_template(), which calls apply_filters() as per the required type template.

While the description for the function get_taxonomy_template() says it uses apply_filters(), which is slightly confusing. An update in description would help understand the actual flow of function calls.

@SergeyBiryukov17 months ago

@SergeyBiryukov17 months ago

comment:2 @SergeyBiryukov17 months ago

  • Component changed from General to Inline Docs
  • Keywords has-patch added
  • Milestone changed from Awaiting Review to 3.9

The filter is already documented in get_query_template(): tags/3.8/src/wp-includes/template.php#L30.

I think we can remove @uses apply_filters() and keep the rest as a regular comment. This should be done consistently for all the functions that use get_query_template(): 26742.2.patch.

comment:3 @DrewAPicture17 months ago

I think doing this is a good idea, as dynamic hooks can be tough to track down. I also think this is an excellent use case for an @uses get_query_template() entry in each phpdoc to serve as a pointer, since all of these are wrappers after all.

As for the added descriptions, I'm not a big fan of the sentence structure of:

"Calls * filter on file path of template.".

Semantically, we don't "call filters", we evaluate them, so for the description, perhaps something like this might work better:

"The template path is filterable via the * hook."

comment:4 @UmeshSingla17 months ago

I agree to @DrewAPicture , @uses get_query_template() would me more appropriate and adding a proper description for how actually filter is being called would be helpful, as I myself is a victim of this dynamic hook
I've updated some of the function description on codex for same.

@DrewAPicture17 months ago

@see + returns + alternative filter description

comment:5 @DrewAPicture17 months ago

  • Keywords commit added

26742.3.patch:

  • @see tags (per inline docs standards, we avoid @uses) for get_query_template() or similar
  • Adds full return descriptions for all of the wrappers
  • Replaces the filter descriptions with the style outlined in comment:3

comment:6 @SergeyBiryukov17 months ago

Looks good to me.

comment:7 @DrewAPicture17 months ago

  • Summary changed from Misleading function description for get_taxonomy_template() in template.php to Improve inline docs for get_*_template() functions

comment:8 @DrewAPicture17 months ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 26906:

Inline documentation improvements for get_*_template() functions in wp-includes/template.php.

  • Adds @see references for get_query_template() or similar
  • Adds complete @return descriptions
  • Clarifies which dynamic hooks can be used to filter specific template types

Props UmeshSingla for the initial patches. Props SergeyBiryukov, DrewAPicture.
Fixes #26742.

comment:9 @ircbot17 months ago

This ticket was mentioned in IRC in #wordpress-dev by DrewAPicture. View the logs.

comment:10 @DrewAPicture15 months ago

  • Focuses docs added

comment:11 @DrewAPicture15 months ago

  • Component changed from Inline Docs to Bootstrap/Load
  • Focuses template added

comment:12 @SergeyBiryukov15 months ago

  • Component changed from Bootstrap/Load to Themes
Note: See TracTickets for help on using tickets.