Improve inline docs for get_*_template() functions

[UmeshSingla]

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.

[UmeshSingla]

removed unwanted description lines for get_taxonomy_template() function

[UmeshSingla]

Patch File

[UmeshSingla]

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

[UmeshSingla]

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.

[SergeyBiryukov]

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

[DrewAPicture]

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

[UmeshSingla]

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.

[DrewAPicture]

@see + returns + alternative filter description

[DrewAPicture]

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

[SergeyBiryukov]

Looks good to me.

[DrewAPicture]

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.