From 33b3ea7bfe6cad71f53f05b0da1bfc12a45afcb3 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Sun, 26 Jul 2020 17:18:04 +0000 Subject: [PATCH] Docs: Improve documentation for various category functions. Props atachibana. Fixes #48394. Built from https://develop.svn.wordpress.org/trunk@48623 git-svn-id: http://core.svn.wordpress.org/trunk@48385 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/category-template.php | 111 +++++++++++++++++++----------- wp-includes/version.php | 2 +- 2 files changed, 71 insertions(+), 42 deletions(-) diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php index edd4468504..46a9c675d0 100644 --- a/wp-includes/category-template.php +++ b/wp-includes/category-template.php @@ -120,15 +120,22 @@ function get_the_category_by_ID( $cat_ID ) { // phpcs:ignore WordPress.NamingCon /** * Retrieves category list for a post in either HTML list or custom format. * + * Generally used for quick, delimited (e.g. comma-separated) lists of categories, + * as part of a post entry meta. + * + * For a more powerful, list-based function, see wp_list_categories(). + * * @since 1.5.1 * + * @see wp_list_categories() + * * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * * @param string $separator Optional. Separator between the categories. By default, the links are placed * 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. */ function get_the_category_list( $separator = '', $parents = '', $post_id = false ) { global $wp_rewrite; @@ -144,8 +151,8 @@ function get_the_category_list( $separator = '', $parents = '', $post_id = false * @since 4.4.0 * * @param WP_Term[] $categories An array of the post's categories. - * @param int|bool $post_id ID of the post we're retrieving categories for. When `false`, we assume the - * current post in the loop. + * @param int|bool $post_id ID of the post we're retrieving categories for. + * When `false`, we assume the current post in the loop. */ $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id ); @@ -272,8 +279,8 @@ function the_category( $separator = '', $parents = '', $post_id = false ) { * * @since 1.0.0 * - * @param int $category Optional. Category ID. Will use global category ID by default. - * @return string Category description, available. + * @param int $category Optional. Category ID. Defaults to the current category ID. + * @return string Category description, if available. */ function category_description( $category = 0 ) { return term_description( $category ); @@ -667,7 +674,11 @@ function wp_list_categories( $args = '' ) { /** * Displays a tag cloud. * + * Outputs 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 { @@ -1164,11 +1175,12 @@ function get_the_tags( $post_id = 0 ) { * * @since 2.3.0 * - * @param string $before Optional. String to use before tags. - * @param string $sep Optional. String to use between the tags. - * @param string $after Optional. String to use after tags. - * @param int $post_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. + * @param string $before Optional. String to use before the tags. Default empty. + * @param string $sep Optional. String to use between the tags. Default empty. + * @param string $after Optional. String to use after the tags. Default empty. + * @param int $post_id Optional. Post ID. Defaults to the current post ID. + * @return string|false|WP_Error A list of tags on success, false if there are no terms, + * WP_Error on failure. */ function get_the_tag_list( $before = '', $sep = '', $after = '', $post_id = 0 ) { $tag_list = get_the_term_list( $post_id, 'post_tag', $before, $sep, $after ); @@ -1179,22 +1191,22 @@ function get_the_tag_list( $before = '', $sep = '', $after = '', $post_id = 0 ) * @since 2.3.0 * * @param string $tag_list List of tags. - * @param string $before String to use before tags. + * @param string $before String to use before the tags. * @param string $sep String to use between the tags. - * @param string $after String to use after tags. + * @param string $after String to use after the tags. * @param int $post_id Post ID. */ return apply_filters( 'the_tags', $tag_list, $before, $sep, $after, $post_id ); } /** - * Retrieves the tags for a post. + * Displays the tags for a post. * * @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. String to use before the tags. Defaults to 'Tags:'. + * @param string $sep Optional. String to use between the tags. Default ', '. + * @param string $after Optional. String to use after the tags. Default empty. */ function the_tags( $before = null, $sep = ', ', $after = '' ) { if ( null === $before ) { @@ -1213,8 +1225,8 @@ function the_tags( $before = null, $sep = ', ', $after = '' ) { * * @since 2.8.0 * - * @param int $tag Optional. Tag ID. Will use global tag ID by default. - * @return string Tag description, available. + * @param int $tag Optional. Tag ID. Defaults to the current tag ID. + * @return string Tag description, if available. */ function tag_description( $tag = 0 ) { return term_description( $tag ); @@ -1226,9 +1238,9 @@ function tag_description( $tag = 0 ) { * @since 2.8.0 * @since 4.9.2 The `$taxonomy` parameter was deprecated. * - * @param int $term Optional. Term ID. Will use global term ID by default. - * @param null $deprecated Deprecated argument. - * @return string Term description, available. + * @param int $term Optional. Term ID. Defaults to the current term ID. + * @param null $deprecated Deprecated. Not used. + * @return string Term description, if available. */ function term_description( $term = 0, $deprecated = null ) { if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) { @@ -1237,7 +1249,9 @@ function term_description( $term = 0, $deprecated = null ) { $term = $term->term_id; } } + $description = get_term_field( 'description', $term ); + return is_wp_error( $description ) ? '' : $description; } @@ -1287,14 +1301,17 @@ function get_the_terms( $post, $taxonomy ) { /** * Retrieves a post's terms as a list with specified format. * + * Terms are linked to their respective term listing pages. + * * @since 2.5.0 * * @param int $post_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 string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure. + * @param string $before Optional. String to use before the terms. Default empty. + * @param string $sep Optional. String to use between the terms. Default empty. + * @param string $after Optional. String to use after the terms. Default empty. + * @return string|false|WP_Error A list of terms on success, false if there are no terms, + * WP_Error on failure. */ function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after = '' ) { $terms = get_the_terms( $post_id, $taxonomy ); @@ -1398,15 +1415,15 @@ function get_term_parents_list( $term_id, $taxonomy, $args = array() ) { } /** - * Displays the terms in a list. + * Displays the terms for a post in a list. * * @since 2.5.0 * * @param int $post_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. + * @param string $before Optional. String to use before the terms. Default empty. + * @param string $sep Optional. String to use between the terms. Default ', '. + * @param string $after Optional. String to use after the terms. Default empty. * @return void|false Void on success, false on failure. */ function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = '' ) { @@ -1433,11 +1450,18 @@ function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = '' /** * Checks 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. + * @param string|int|array $category Optional. The category name/term_id/slug, + * or an array of them to check for. Default empty. * @param int|object $post Optional. Post to check instead of the current post. - * @return bool True if the current post has any of the given categories (or any category, if no category specified). + * @return bool True if the current post has any of the given categories + * (or any category, if no category specified). False otherwise. */ function has_category( $category = '', $post = null ) { return has_term( $category, 'category', $post ); @@ -1448,21 +1472,23 @@ function has_category( $category = '', $post = null ) { * * The given tags are checked against the post's tags' term_ids, names and slugs. * Tags given as integers will only be checked against the post's tags' term_ids. - * If no tags are given, determines if post has any tags. * - * Prior to v2.7 of WordPress, tags given as integers would also be checked against the post's tags' names and slugs (in addition to term_ids) - * Prior to v2.7, this function could only be used in the WordPress Loop. - * As of 2.7, the function can be used anywhere if it is provided a post ID or post object. + * If no tags are given, determines if post has any tags. * * For more information on this and similar theme functions, check out * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ * Conditional Tags} article in the Theme Developer Handbook. * * @since 2.6.0 + * @since 2.7.0 Tags given as integers are only checked against + * the post's tags' term_ids, not names or slugs. + * @since 2.7.0 Can be used outside of the WordPress Loop if `$post` is provided. * - * @param string|int|array $tag Optional. The tag name/term_id/slug or array of them to check for. - * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0) - * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). + * @param string|int|array $tag Optional. The tag name/term_id/slug, + * or an array of them to check for. Default empty. + * @param int|object $post Optional. Post to check instead of the current post. + * @return bool True if the current post has any of the given tags + * (or any tag, if no tag specified). False otherwise. */ function has_tag( $tag = '', $post = null ) { return has_term( $tag, 'post_tag', $post ); @@ -1473,14 +1499,17 @@ function has_tag( $tag = '', $post = null ) { * * The given terms are checked against the post's terms' term_ids, names and slugs. * Terms given as integers will only be checked against the post's terms' term_ids. + * * If no terms are given, determines if post has any terms. * * @since 3.1.0 * - * @param string|int|array $term Optional. The term name/term_id/slug or array of them to check for. - * @param string $taxonomy Taxonomy name. + * @param string|int|array $term Optional. The term name/term_id/slug, + * or an array of them to check for. Default empty. + * @param string $taxonomy Optional. Taxonomy name. Default empty. * @param int|WP_Post $post Optional. Post to check instead of the current post. - * @return bool True if the current post has any of the given tags (or any tag, if no tag specified). + * @return bool True if the current post has any of the given terms + * (or any term, if no term specified). False otherwise. */ function has_term( $term = '', $taxonomy = '', $post = null ) { $post = get_post( $post ); diff --git a/wp-includes/version.php b/wp-includes/version.php index 9f8a01d89f..728fb02c40 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.5-beta3-48622'; +$wp_version = '5.5-beta3-48623'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.