Make WordPress Core


Ignore:
Timestamp:
05/29/2020 10:05:36 AM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve documentation for functions in wp-includes/category.php per the documentation standards.

See #49572.

File:
1 edited

Legend:

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

    r47863 r47864  
    88
    99/**
    10  * Retrieve list of category objects.
     10 * Retrieves a list of category objects.
    1111 *
    1212 * If you set the 'taxonomy' argument to 'link_category', the link categories
     
    8181 *
    8282 * @param int|object $category Category ID or Category row object
    83  * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a
    84  *                       WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
     83 * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N,
     84 *                       which correspond to a WP_Term object, an associative array, or a numeric array,
     85 *                       respectively. Default OBJECT.
    8586 * @param string $filter Optional. Default is raw or no WordPress defined filter will applied.
    8687 * @return object|array|WP_Error|null Category data in type defined by $output parameter.
     
    100101
    101102/**
    102  * Retrieve category based on URL containing the category slug.
     103 * Retrieves a category based on URL containing the category slug.
    103104 *
    104105 * Breaks the $category_path parameter up to get the category slug.
     
    115116 * @param string $category_path URL containing category slugs.
    116117 * @param bool   $full_match    Optional. Whether full path should be matched.
    117  * @param string $output        Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    118  *                              a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
     118 * @param string $output        Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N,
     119 *                              which correspond to a WP_Term object, an associative array, or a numeric array,
     120 *                              respectively. Default OBJECT.
    119121 * @return WP_Term|array|WP_Error|null Type is based on $output value.
    120122 */
     
    149151        while ( ( 0 != $curcategory->parent ) && ( $curcategory->parent != $curcategory->term_id ) ) {
    150152            $curcategory = get_term( $curcategory->parent, 'category' );
     153
    151154            if ( is_wp_error( $curcategory ) ) {
    152155                return $curcategory;
    153156            }
     157
    154158            $path = '/' . $curcategory->slug . $path;
    155159        }
     
    158162            $category = get_term( $category->term_id, 'category', $output );
    159163            _make_cat_compat( $category );
     164
    160165            return $category;
    161166        }
     
    166171        $category = get_term( reset( $categories )->term_id, 'category', $output );
    167172        _make_cat_compat( $category );
     173
    168174        return $category;
    169175    }
     
    171177
    172178/**
    173  * Retrieve category object by category slug.
     179 * Retrieves a category object by category slug.
    174180 *
    175181 * @since 2.3.0
     
    189195
    190196/**
    191  * Retrieve the ID of a category from its name.
     197 * Retrieves the ID of a category from its name.
    192198 *
    193199 * @since 1.0.0
    194200 *
    195201 * @param string $cat_name Category name.
    196  * @return int 0, if failure and ID of category on success.
     202 * @return int Category ID on success, 0 if the category doesn't exist.
    197203 */
    198204function get_cat_ID( $cat_name ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
    199205    $cat = get_term_by( 'name', $cat_name, 'category' );
     206
    200207    if ( $cat ) {
    201208        return $cat->term_id;
    202209    }
     210
    203211    return 0;
    204212}
    205213
    206214/**
    207  * Retrieve the name of a category from its ID.
     215 * Retrieves the name of a category from its ID.
    208216 *
    209217 * @since 1.0.0
    210218 *
    211  * @param int $cat_id Category ID
    212  * @return string Category name, or an empty string if category doesn't exist.
     219 * @param int $cat_id Category ID.
     220 * @return string Category name, or an empty string if the category doesn't exist.
    213221 */
    214222function get_cat_name( $cat_id ) {
    215223    $cat_id   = (int) $cat_id;
    216224    $category = get_term( $cat_id, 'category' );
     225
    217226    if ( ! $category || is_wp_error( $category ) ) {
    218227        return '';
    219228    }
     229
    220230    return $category->name;
    221231}
    222232
    223233/**
    224  * Check if a category is an ancestor of another category.
    225  *
    226  * You can use either an id or the category object for both parameters. If you
    227  * use an integer the category will be retrieved.
     234 * Checks if a category is an ancestor of another category.
     235 *
     236 * You can use either an ID or the category object for both parameters.
     237 * If you use an integer, the category will be retrieved.
    228238 *
    229239 * @since 2.1.0
     
    231241 * @param int|object $cat1 ID or object to check if this is the parent category.
    232242 * @param int|object $cat2 The child category.
    233  * @return bool Whether $cat2 is child of $cat1
     243 * @return bool Whether $cat2 is child of $cat1.
    234244 */
    235245function cat_is_ancestor_of( $cat1, $cat2 ) {
     
    242252 * @since 2.3.0
    243253 *
    244  * @param object|array $category Category data
    245  * @param string $context Optional. Default is 'display'.
     254 * @param object|array $category Category data.
     255 * @param string       $context  Optional. Default 'display'.
    246256 * @return object|array Same type as $category with sanitized data for safe use.
    247257 */
     
    255265 * @since 2.3.0
    256266 *
    257  * @param string $field Category key to sanitize
    258  * @param mixed $value Category value to sanitize
    259  * @param int $cat_id Category ID
     267 * @param string $field   Category key to sanitize.
     268 * @param mixed  $value   Category value to sanitize.
     269 * @param int    $cat_id  Category ID.
    260270 * @param string $context What filter to use, 'raw', 'display', etc.
    261271 * @return mixed Same type as $value after $value has been sanitized.
     
    296306     */
    297307    $tags = apply_filters( 'get_tags', $tags, $args );
     308
    298309    return $tags;
    299310}
    300311
    301312/**
    302  * Retrieve post tag by tag ID or tag object.
     313 * Retrieves a post tag by tag ID or tag object.
    303314 *
    304315 * If you pass the $tag parameter an object, which is assumed to be the tag row
    305  * object retrieved the database. It will cache the tag data.
    306  *
    307  * If you pass $tag an integer of the tag ID, then that tag will
    308  * be retrieved from the database, if it isn't already cached, and pass it back.
    309  *
    310  * If you look at get_term(), then both types will be passed through several
    311  * filters and finally sanitized based on the $filter parameter value.
     316 * object retrieved from the database, it will cache the tag data.
     317 *
     318 * If you pass $tag an integer of the tag ID, then that tag will be retrieved
     319 * from the database, if it isn't already cached, and passed back.
     320 *
     321 * If you look at get_term(), both types will be passed through several filters
     322 * and finally sanitized based on the $filter parameter value.
    312323 *
    313324 * @since 2.3.0
    314325 *
    315326 * @param int|WP_Term|object $tag    A tag ID or object.
    316  * @param string             $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    317  *                                   a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
     327 * @param string             $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N,
     328 *                                   which correspond to a WP_Term object, an associative array, or a numeric array,
     329 *                                   respectively. Default OBJECT.
    318330 * @param string             $filter Optional. Default is raw or no WordPress defined filter will applied.
    319  * @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter. WP_Error if $tag is empty, null if it does not exist.
     331 * @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter.
     332 *                                     WP_Error if $tag is empty, null if it does not exist.
    320333 */
    321334function get_tag( $tag, $output = OBJECT, $filter = 'raw' ) {
     
    326339
    327340/**
    328  * Remove the category cache data based on ID.
     341 * Removes the category cache data based on ID.
    329342 *
    330343 * @since 2.1.0
     
    337350
    338351/**
    339  * Update category structure to old pre-2.3 from new taxonomy structure.
     352 * Updates category structure to old pre-2.3 from new taxonomy structure.
    340353 *
    341354 * This function was added for the taxonomy support to update the new category
Note: See TracChangeset for help on using the changeset viewer.