WordPress.org

Make WordPress Core

Changeset 48623


Ignore:
Timestamp:
07/26/2020 05:16:32 PM (2 months ago)
Author:
SergeyBiryukov
Message:

Docs: Improve documentation for various category functions.

Props atachibana.
Fixes #48394.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/category-template.php

    r48622 r48623  
    121121 * Retrieves category list for a post in either HTML list or custom format.
    122122 *
     123 * Generally used for quick, delimited (e.g. comma-separated) lists of categories,
     124 * as part of a post entry meta.
     125 *
     126 * For a more powerful, list-based function, see wp_list_categories().
     127 *
    123128 * @since 1.5.1
     129 *
     130 * @see wp_list_categories()
    124131 *
    125132 * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
     
    129136 * @param string $parents   Optional. How to display the parents.
    130137 * @param int    $post_id   Optional. Post ID to retrieve categories.
    131  * @return string
     138 * @return string Category list for a post.
    132139 */
    133140function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
     
    145152     *
    146153     * @param WP_Term[] $categories An array of the post's categories.
    147      * @param int|bool  $post_id    ID of the post we're retrieving categories for. When `false`, we assume the
    148      *                              current post in the loop.
     154     * @param int|bool  $post_id    ID of the post we're retrieving categories for.
     155     *                              When `false`, we assume the current post in the loop.
    149156     */
    150157    $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
     
    273280 * @since 1.0.0
    274281 *
    275  * @param int $category Optional. Category ID. Will use global category ID by default.
    276  * @return string Category description, available.
     282 * @param int $category Optional. Category ID. Defaults to the current category ID.
     283 * @return string Category description, if available.
    277284 */
    278285function category_description( $category = 0 ) {
     
    668675 * Displays a tag cloud.
    669676 *
     677 * Outputs a list of tags in what is called a 'tag cloud', where the size of each tag
     678 * is determined by how many times that particular tag has been assigned to posts.
     679 *
    670680 * @since 2.3.0
     681 * @since 2.8.0 Added the `taxonomy` argument.
    671682 * @since 4.8.0 Added the `show_count` argument.
    672683 *
     
    11651176 * @since 2.3.0
    11661177 *
    1167  * @param string $before  Optional. String to use before tags.
    1168  * @param string $sep     Optional. String to use between the tags.
    1169  * @param string $after   Optional. String to use after tags.
    1170  * @param int    $post_id Optional. Post ID. Defaults to the current post.
    1171  * @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure.
     1178 * @param string $before  Optional. String to use before the tags. Default empty.
     1179 * @param string $sep     Optional. String to use between the tags. Default empty.
     1180 * @param string $after   Optional. String to use after the tags. Default empty.
     1181 * @param int    $post_id Optional. Post ID. Defaults to the current post ID.
     1182 * @return string|false|WP_Error A list of tags on success, false if there are no terms,
     1183 *                               WP_Error on failure.
    11721184 */
    11731185function get_the_tag_list( $before = '', $sep = '', $after = '', $post_id = 0 ) {
     
    11801192     *
    11811193     * @param string $tag_list List of tags.
    1182      * @param string $before   String to use before tags.
     1194     * @param string $before   String to use before the tags.
    11831195     * @param string $sep      String to use between the tags.
    1184      * @param string $after    String to use after tags.
     1196     * @param string $after    String to use after the tags.
    11851197     * @param int    $post_id  Post ID.
    11861198     */
     
    11891201
    11901202/**
    1191  * Retrieves the tags for a post.
     1203 * Displays the tags for a post.
    11921204 *
    11931205 * @since 2.3.0
    11941206 *
    1195  * @param string $before Optional. Before list.
    1196  * @param string $sep Optional. Separate items using this.
    1197  * @param string $after Optional. After list.
     1207 * @param string $before Optional. String to use before the tags. Defaults to 'Tags:'.
     1208 * @param string $sep    Optional. String to use between the tags. Default ', '.
     1209 * @param string $after  Optional. String to use after the tags. Default empty.
    11981210 */
    11991211function the_tags( $before = null, $sep = ', ', $after = '' ) {
     
    12141226 * @since 2.8.0
    12151227 *
    1216  * @param int $tag Optional. Tag ID. Will use global tag ID by default.
    1217  * @return string Tag description, available.
     1228 * @param int $tag Optional. Tag ID. Defaults to the current tag ID.
     1229 * @return string Tag description, if available.
    12181230 */
    12191231function tag_description( $tag = 0 ) {
     
    12271239 * @since 4.9.2 The `$taxonomy` parameter was deprecated.
    12281240 *
    1229  * @param int  $term       Optional. Term ID. Will use global term ID by default.
    1230  * @param null $deprecated Deprecated argument.
    1231  * @return string Term description, available.
     1241 * @param int  $term       Optional. Term ID. Defaults to the current term ID.
     1242 * @param null $deprecated Deprecated. Not used.
     1243 * @return string Term description, if available.
    12321244 */
    12331245function term_description( $term = 0, $deprecated = null ) {
     
    12381250        }
    12391251    }
     1252
    12401253    $description = get_term_field( 'description', $term );
     1254
    12411255    return is_wp_error( $description ) ? '' : $description;
    12421256}
     
    12881302 * Retrieves a post's terms as a list with specified format.
    12891303 *
     1304 * Terms are linked to their respective term listing pages.
     1305 *
    12901306 * @since 2.5.0
    12911307 *
    12921308 * @param int    $post_id  Post ID.
    12931309 * @param string $taxonomy Taxonomy name.
    1294  * @param string $before   Optional. Before list.
    1295  * @param string $sep      Optional. Separate items using this.
    1296  * @param string $after    Optional. After list.
    1297  * @return string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure.
     1310 * @param string $before   Optional. String to use before the terms. Default empty.
     1311 * @param string $sep      Optional. String to use between the terms. Default empty.
     1312 * @param string $after    Optional. String to use after the terms. Default empty.
     1313 * @return string|false|WP_Error A list of terms on success, false if there are no terms,
     1314 *                               WP_Error on failure.
    12981315 */
    12991316function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after = '' ) {
     
    13991416
    14001417/**
    1401  * Displays the terms in a list.
     1418 * Displays the terms for a post in a list.
    14021419 *
    14031420 * @since 2.5.0
     
    14051422 * @param int    $post_id  Post ID.
    14061423 * @param string $taxonomy Taxonomy name.
    1407  * @param string $before   Optional. Before list.
    1408  * @param string $sep      Optional. Separate items using this.
    1409  * @param string $after    Optional. After list.
     1424 * @param string $before   Optional. String to use before the terms. Default empty.
     1425 * @param string $sep      Optional. String to use between the terms. Default ', '.
     1426 * @param string $after    Optional. String to use after the terms. Default empty.
    14101427 * @return void|false Void on success, false on failure.
    14111428 */
     
    14341451 * Checks if the current post has any of given category.
    14351452 *
     1453 * The given categories are checked against the post's categories' term_ids, names and slugs.
     1454 * Categories given as integers will only be checked against the post's categories' term_ids.
     1455 *
     1456 * If no categories are given, determines if post has any categories.
     1457 *
    14361458 * @since 3.1.0
    14371459 *
    1438  * @param string|int|array $category Optional. The category name/term_id/slug or array of them to check for.
     1460 * @param string|int|array $category Optional. The category name/term_id/slug,
     1461 *                                   or an array of them to check for. Default empty.
    14391462 * @param int|object       $post     Optional. Post to check instead of the current post.
    1440  * @return bool True if the current post has any of the given categories (or any category, if no category specified).
     1463 * @return bool True if the current post has any of the given categories
     1464 *              (or any category, if no category specified). False otherwise.
    14411465 */
    14421466function has_category( $category = '', $post = null ) {
     
    14491473 * The given tags are checked against the post's tags' term_ids, names and slugs.
    14501474 * Tags given as integers will only be checked against the post's tags' term_ids.
     1475 *
    14511476 * If no tags are given, determines if post has any tags.
    1452  *
    1453  * 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)
    1454  * Prior to v2.7, this function could only be used in the WordPress Loop.
    1455  * As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
    14561477 *
    14571478 * For more information on this and similar theme functions, check out
     
    14601481 *
    14611482 * @since 2.6.0
    1462  *
    1463  * @param string|int|array $tag  Optional. The tag name/term_id/slug or array of them to check for.
    1464  * @param int|object       $post Optional. Post to check instead of the current post. (since 2.7.0)
    1465  * @return bool True if the current post has any of the given tags (or any tag, if no tag specified).
     1483 * @since 2.7.0 Tags given as integers are only checked against
     1484 *              the post's tags' term_ids, not names or slugs.
     1485 * @since 2.7.0 Can be used outside of the WordPress Loop if `$post` is provided.
     1486 *
     1487 * @param string|int|array $tag  Optional. The tag name/term_id/slug,
     1488 *                               or an array of them to check for. Default empty.
     1489 * @param int|object       $post Optional. Post to check instead of the current post.
     1490 * @return bool True if the current post has any of the given tags
     1491 *              (or any tag, if no tag specified). False otherwise.
    14661492 */
    14671493function has_tag( $tag = '', $post = null ) {
     
    14741500 * The given terms are checked against the post's terms' term_ids, names and slugs.
    14751501 * Terms given as integers will only be checked against the post's terms' term_ids.
     1502 *
    14761503 * If no terms are given, determines if post has any terms.
    14771504 *
    14781505 * @since 3.1.0
    14791506 *
    1480  * @param string|int|array $term     Optional. The term name/term_id/slug or array of them to check for.
    1481  * @param string           $taxonomy Taxonomy name.
     1507 * @param string|int|array $term     Optional. The term name/term_id/slug,
     1508 *                                   or an array of them to check for. Default empty.
     1509 * @param string           $taxonomy Optional. Taxonomy name. Default empty.
    14821510 * @param int|WP_Post      $post     Optional. Post to check instead of the current post.
    1483  * @return bool True if the current post has any of the given tags (or any tag, if no tag specified).
     1511 * @return bool True if the current post has any of the given terms
     1512 *              (or any term, if no term specified). False otherwise.
    14841513 */
    14851514function has_term( $term = '', $taxonomy = '', $post = null ) {
Note: See TracChangeset for help on using the changeset viewer.