PHPDoc correction for functions in wp-includes/category-template.php

[atachibana]

Enhanced missing information of Codex to Code Reference

Index: category-template.php
===================================================================
--- category-template.php	(revision 46568)
+++ category-template.php	(working copy)

get_category_link
Codex: ​https://codex.wordpress.org/Function_Reference/get_category_link
Code Reference: ​https://developer.wordpress.org/reference/functions/get_category_link/

@@ -10,6 +10,10 @@
 /**
  * Retrieve category link URL.
  *
+ * Returns the correct url for a given Category ID.
+ * In a Plugin or Theme, it can be used as early as the setup_theme Action.
+ * Any earlier usage, including plugins_loaded, generates a Fatal Error.
+ *
  * @since 1.0.0
  * @see get_term_link()
  *

get_the_category_list
Codex: ​https://codex.wordpress.org/Function_Reference/get_the_category_list
Code Reference: ​https://developer.wordpress.org/reference/functions/get_the_category_list/

@@ -119,6 +123,9 @@
 /**
  * Retrieve category list for a post in either HTML list or custom format.
  *
+ * Generally used for quick, delimited (eg: comma-separated) lists of categories, as part of a post's entry meta.
+ * For a more powerful, list-based function, see wp_list_categories().
+ *
  * @since 1.5.1
  *
  * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
@@ -127,7 +134,7 @@
  *                          in an unordered list. An empty string will result in the default behavior.
  * @param string $parents Optional. How to display the parents.
  * @param int $post_id Optional. Post ID to retrieve categories.
- * @return string
+ * @return string Category list for a post in either HTML list or custom format.
  */
 function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
 	global $wp_rewrite;

category_description
Codex: ​https://codex.wordpress.org/Function_Reference/category_description
Code Reference: ​https://developer.wordpress.org/reference/functions/category_description/

@@ -267,6 +274,9 @@
 /**
  * Retrieve category description.
  *
+ * If used in the archive.php template, place this function within the is_category() conditional statement.
+ * Otherwise, this function will stop the processing of the page for monthly and other archive pages.
+ *
  * @since 1.0.0
  *
  * @param int $category Optional. Category ID. Will use global category ID by default.

wp_tag_cloud
Codex: ​https://codex.wordpress.org/Function_Reference/wp_tag_cloud
Code Reference: ​https://developer.wordpress.org/reference/functions/wp_tag_cloud/

@@ -655,7 +665,11 @@
 /**
  * Displays a tag cloud.
  *
+ * It displays a list of tags in what is called a 'tag cloud', where the size of each tag is determined
+ * by how many times that particular tag has been assigned to posts.
+ *
  * @since 2.3.0
+ * @since 2.8.0 Added the `taxonomy` argument.
  * @since 4.8.0 Added the `show_count` argument.
  *
  * @param array|string $args {

get_the_tags
Codex: ​https://codex.wordpress.org/Function_Reference/get_the_tags
Code Reference: ​https://developer.wordpress.org/reference/functions/get_the_tags/

@@ -1117,6 +1131,9 @@
 /**
  * Retrieve the tags for a post.
  *
+ * Returns an array of objects, one object for each tag assigned to the post.
+ * If this function is used in The Loop, then no ID need be passed.
+ *
  * @since 2.3.0
  *
  * @param int $id Post ID.

get_the_tag_list
Codex: ​https://codex.wordpress.org/Function_Reference/get_the_tag_list
Code Reference: ​https://developer.wordpress.org/reference/functions/get_the_tag_list/

@@ -1139,11 +1156,16 @@
 /**
  * Retrieve the tags for a post formatted as a string.
  *
+ * Generates a HTML string of the tags associated with the current post.
+ * The name of each tag will be linked to the relevant 'tag' page.
+ * You can tell the function to put a string before and after all the tags, and in between each tag.
+ * Differently from get_the_category_list, this tag must be used inside The Loop.
+ *
  * @since 2.3.0
  *
- * @param string $before Optional. Before tags.
- * @param string $sep Optional. Between tags.
- * @param string $after Optional. After tags.
+ * @param string $before Optional. Leading text before list.
+ * @param string $sep Optional. String to separate tags.
+ * @param string $after Optional. Trailing text after list.
  * @param int $id Optional. Post ID. Defaults to the current post.
  * @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure.
  */

the_tags
Codex: ​https://codex.wordpress.org/Function_Reference/the_tags
Code Reference: ​https://developer.wordpress.org/reference/functions/the_tags/

@@ -1166,11 +1188,14 @@
 /**
  * Retrieve the tags for a post.
  *
+ * Displays a link to the tag or tags a post belongs to. If no tags are associated with the current entry,
+ * nothing is displayed. Should be used within The Loop.
+ *
  * @since 2.3.0
  *
- * @param string $before Optional. Before list.
- * @param string $sep Optional. Separate items using this.
- * @param string $after Optional. After list.
+ * @param string $before Optional. Text to display before the actual tags are displayed. Default is 'Tags: '.
+ * @param string $sep Optional. Text or character to display between each tag link. The default is a comma (,) between each tag.
+ * @param string $after Optional. Text to display after the last tag. The default is to display nothing.
  */
 function the_tags( $before = null, $sep = ', ', $after = '' ) {
 	if ( null === $before ) {

tag_description
Codex: ​https://codex.wordpress.org/Function_Reference/tag_description
Code Reference ​https://developer.wordpress.org/reference/functions/tag_description/

@@ -1187,6 +1212,9 @@
 /**
  * Retrieve tag description.
  *
+ * It returns the description of a tag.
+ * If no tag ID is passed, the description of current queried tag will be returned.
+ *
  * @since 2.8.0
  *
  * @param int $tag Optional. Tag ID. Will use global tag ID by default.

term_description
Codex: ​https://codex.wordpress.org/Function_Reference/term_description
Code Reference ​https://developer.wordpress.org/reference/functions/term_description/

@@ -1199,6 +1227,9 @@
 /**
  * Retrieve term description.
  *
+ * It returns the description of a given term.
+ * If no term ID is passed, the description of current queried term (e.g. post category or tag) will be returned.
+ *
  * @since 2.8.0
  * @since 4.9.2 The `$taxonomy` parameter was deprecated.
  *

get_the_term_list
Codex: ​https://codex.wordpress.org/Function_Reference/get_the_term_list
Code Reference ​https://developer.wordpress.org/reference/functions/get_the_term_list/

@@ -1263,14 +1294,17 @@
 /**
  * Retrieve a post's terms as a list with specified format.
  *
+ * Returns an HTML string of taxonomy terms associated with a post and given taxonomy.
+ * Terms are linked to their respective term listing pages.
+ *
  * @since 2.5.0
  *
  * @param int $id Post ID.
  * @param string $taxonomy Taxonomy name.
- * @param string $before Optional. Before list.
+ * @param string $before Optional. Leading text before list.
  * @param string $sep Optional. Separate items using this.
- * @param string $after Optional. After list.
- * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure.
+ * @param string $after Optional. Trailing text after list.
+ * @return string|false|WP_Error HTML string of list of terms on success, false if there are no terms, WP_Error on failure.
  */
 function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
 	$terms = get_the_terms( $id, $taxonomy );

the_terms
Codex: ​https://codex.wordpress.org/Function_Reference/the_terms
Code Reference ​https://developer.wordpress.org/reference/functions/the_terms

@@ -1374,16 +1408,17 @@
 }
 
 /**
- * Display the terms in a list.
+ * Displays a string of linked terms for a post.
  *
  * @since 2.5.0
  *
  * @param int $id Post ID.
  * @param string $taxonomy Taxonomy name.
- * @param string $before Optional. Before list.
- * @param string $sep Optional. Separate items using this.
- * @param string $after Optional. After list.
- * @return false|void False on WordPress error.
+ * @param string $before Optional. Text to display before the actual tags are displayed.
+ * @param string $sep Optional. Text or character to display between each tag link.
+ * @param string $after Optional. Text to display after the last tag.
+ * @return false|void False on WordPress error. Otherwise, it displays the linked terms of a custom taxonomies
+ *                    separated by user defined characters, and will not return a value.
  */
 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
 	$term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );

has_category
Codex: ​https://codex.wordpress.org/Function_Reference/has_category
Code Reference: ​https://developer.wordpress.org/reference/functions/has_category/

@@ -1409,6 +1444,11 @@
 /**
  * Check if the current post has any of given category.
  *
+ * The given categories are checked against the post's categories' term_ids, names and slugs.
+ * Categories given as integers will only be checked against the post's categories' term_ids.
+ *
+ * If no categories are given, determines if post has any categories.
+ *
  * @since 3.1.0
  *
  * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for.

[SergeyBiryukov]

Thanks for the patch! Would like to give this a closer look for consistency, moving to 5.5 for now.

[SergeyBiryukov]

In 48623:

Docs: Improve documentation for various category functions.

Props atachibana.
Fixes #48394.