[wp-trac] [WordPress Trac] #48394: PHPDoc correction for functions in wp-includes/category-template.php
WordPress Trac
noreply at wordpress.org
Tue Oct 22 09:24:34 UTC 2019
#48394: PHPDoc correction for functions in wp-includes/category-template.php
--------------------------+-----------------------------
Reporter: atachibana | Owner: (none)
Type: defect (bug) | Status: new
Priority: normal | Milestone: Awaiting Review
Component: Taxonomy | Version:
Severity: minor | Keywords:
Focuses: docs |
--------------------------+-----------------------------
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.
}}}
--
Ticket URL: <https://core.trac.wordpress.org/ticket/48394>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform
More information about the wp-trac
mailing list