WordPress.org
Get WordPress

Make WordPress Core

Changeset 32627


Ignore:
Timestamp:
05/27/2015 09:59:06 PM (10 years ago)
Author:
wonderboymusic
Message:

Add missing doc blocks to taxonomy.php.
Correct some @return values.
Some functions can return new WP_Error without setting it to a variable.
Some functions can return their apply_filters(...) call without first setting it to a variable.
is_object_in_taxonomy() can return its conditional instead of if/else true/false.

See #32444.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/taxonomy.php

    r32553 r32627  
    171171 * @global array $wp_taxonomies The registered taxonomies.
    172172 *
    173  * @param array|string|object $object Name of the type of taxonomy object, or an object (row from posts)
    174  * @param string              $output Optional. The type of output to return in the array. Accepts either
    175  *                            taxonomy 'names' or 'objects'. Default 'names'.
     173 * @param array|string|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
     174 * @param string               $output Optional. The type of output to return in the array. Accepts either
     175 *                                     taxonomy 'names' or 'objects'. Default 'names'.
    176176 * @return array The names of all taxonomy of $object_type.
    177177 */
    … …  
    211211 *
    212212 * @param string $taxonomy Name of taxonomy object to return.
    213  * @return object|bool The Taxonomy Object or false if $taxonomy doesn't exist.
     213 * @return object|false The Taxonomy Object or false if $taxonomy doesn't exist.
    214214 */
    215215function get_taxonomy( $taxonomy ) {
    … …  
    328328 * @global WP    $wp            WP instance.
    329329 *
    330  * @param string $taxonomy Taxonomy key, must not exceed 32 characters.
     330 * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
    331331 * @param array|string $object_type Name of the object type for the taxonomy object.
    332  * @param array|string $args See optional args description above.
    333  * @return null|WP_Error WP_Error if errors, otherwise null.
     332 * @param array|string $args        See optional args description above.
     333 * @return WP_Error|void WP_Error, if errors.
    334334 */
    335335function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
    … …  
    483483 * @return object object with all the labels as member variables.
    484484 */
    485 
    486485function get_taxonomy_labels( $tax ) {
    487486    $tax->labels = (array) $tax->labels;
    … …  
    593592 * @global wpdb $wpdb WordPress database abstraction object.
    594593 *
    595  * @param int|array $term_ids Term id or array of term ids of terms that will be used.
     594 * @param int|array    $term_ids  Term id or array of term ids of terms that will be used.
    596595 * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
    597  * @param array|string $args Change the order of the object_ids, either ASC or DESC.
     596 * @param array|string $args       Change the order of the object_ids, either ASC or DESC.
    598597 * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success.
    599598 *  the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
    … …  
    639638 * @see WP_Tax_Query
    640639 *
    641  * @param array $tax_query A compact tax query
     640 * @param array  $tax_query        A compact tax query
    642641 * @param string $primary_table
    643642 * @param string $primary_id_column
    … …  
    684683     *
    685684     * @since 3.2.0
     685     *
     686     * @static
    686687     * @access private
    687688     * @var string
    … …  
    867868     *
    868869     * @since 4.1.0
     870     *
     871     * @static
    869872     * @access protected
    870873     *
    … …  
    880883     *
    881884     * @since 3.1.0
     885     *
     886     * @static
    882887     * @access public
    883888     *
    … …  
    11481153     * @param array       $clause       Query clause.
    11491154     * @param array       $parent_query Parent query of $clause.
    1150      * @return string|bool Table alias if found, otherwise false.
     1155     * @return string|false Table alias if found, otherwise false.
    11511156     */
    11521157    protected function find_compatible_table_alias( $clause, $parent_query ) {
    … …  
    13291334 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
    13301335 *
    1331  * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
    1332  * @param string $taxonomy Taxonomy name that $term is part of.
    1333  * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
    1334  * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
    1335  * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
     1336 * @param int|object $term     If integer, will get from database. If object will apply filters and return $term.
     1337 * @param string     $taxonomy Taxonomy name that $term is part of.
     1338 * @param string     $output  Constant OBJECT, ARRAY_A, or ARRAY_N
     1339 * @param string     $filter  Optional, default is raw or no WordPress defined filter will applied.
     1340 * @return object|array|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
    13361341 * exist then WP_Error will be returned.
    13371342 */
    … …  
    13391344    global $wpdb;
    13401345
    1341     if ( empty($term) ) {
    1342         $error = new WP_Error('invalid_term', __('Empty Term'));
    1343         return $error;
    1344     }
    1345 
    1346     if ( ! taxonomy_exists($taxonomy) ) {
    1347         $error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
    1348         return $error;
     1346    if ( empty( $term ) ) {
     1347        return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
     1348    }
     1349
     1350    if ( ! taxonomy_exists( $taxonomy ) ) {
     1351        return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
    13491352    }
    13501353
    … …  
    14211424 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
    14221425 *
    1423  * @param string $field Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
    1424  * @param string|int $value Search for this term value
    1425  * @param string $taxonomy Taxonomy Name
    1426  * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
    1427  * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
    1428  * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found.
     1426 * @param string     $field    Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
     1427 * @param string|int $value    Search for this term value
     1428 * @param string     $taxonomy Taxonomy Name
     1429 * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
     1430 * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
     1431 * @return object|array|null|WP_Error|false Term Row from database.
     1432 *                                          Will return false if $taxonomy does not exist or $term was not found.
    14291433 */
    14301434function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
    … …  
    15301534 * @param string $taxonomy Taxonomy Name.
    15311535 * @param string $context  Optional, default is display. Look at sanitize_term_field() for available options.
    1532  * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term.
     1536 * @return string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
    15331537 */
    15341538function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
    … …  
    15571561 * @param int|object $id       Term ID or object.
    15581562 * @param string     $taxonomy Taxonomy name.
    1559  * @return mixed|null|WP_Error Will return empty string if $term is not an object.
     1563 * @return string|int|null|WP_Error Will return empty string if $term is not an object.
    15601564 */
    15611565function get_term_to_edit( $id, $taxonomy ) {
    … …  
    15911595 * @since 4.2.0 Introduced 'name' and 'childless' parameters.
    15921596 *
    1593  * @global wpdb $wpdb WordPress database abstraction object.
     1597 * @global wpdb  $wpdb WordPress database abstraction object.
     1598 * @global array $wp_filter
    15941599 *
    15951600 * @param string|array $taxonomies Taxonomy name or list of Taxonomy names.
    … …  
    16421647 *                                           object cache. Default is 'core'.
    16431648 * }
    1644  * @return array|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
     1649 * @return array|int|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
    16451650 *                        do not exist.
    16461651 */
    … …  
    16561661    foreach ( $taxonomies as $taxonomy ) {
    16571662        if ( ! taxonomy_exists($taxonomy) ) {
    1658             $error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
    1659             return $error;
     1663            return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
    16601664        }
    16611665    }
    … …  
    17541758         * @param array $args       An array of get_terms() arguments.
    17551759         */
    1756         $cache = apply_filters( 'get_terms', $cache, $taxonomies, $args );
    1757         return $cache;
     1760        return apply_filters( 'get_terms', $cache, $taxonomies, $args );
    17581761    }
    17591762
    … …  
    19961999
    19972000    if ( 'count' == $_fields ) {
    1998         $term_count = $wpdb->get_var($query);
    1999         return $term_count;
     2001        return $wpdb->get_var( $query );
    20002002    }
    20012003
    … …  
    20092011
    20102012        /** This filter is documented in wp-includes/taxonomy.php */
    2011         $terms = apply_filters( 'get_terms', array(), $taxonomies, $args );
    2012         return $terms;
     2013        return apply_filters( 'get_terms', array(), $taxonomies, $args );
    20132014    }
    20142015
    … …  
    20832084
    20842085    /** This filter is documented in wp-includes/taxonomy */
    2085     $terms = apply_filters( 'get_terms', $terms, $taxonomies, $args );
    2086     return $terms;
     2086    return apply_filters( 'get_terms', $terms, $taxonomies, $args );
    20872087}
    20882088
    … …  
    20962096 * @global wpdb $wpdb WordPress database abstraction object.
    20972097 *
    2098  * @param int|string $term The term to check
    2099  * @param string $taxonomy The taxonomy name to use
    2100  * @param int $parent Optional. ID of parent term under which to confine the exists search.
     2098 * @param int|string $term     The term to check
     2099 * @param string     $taxonomy The taxonomy name to use
     2100 * @param int        $parent  Optional. ID of parent term under which to confine the exists search.
    21012101 * @return mixed Returns null if the term does not exist. Returns the term ID
    21022102 *               if no taxonomy is specified and the term ID exists. Returns
    … …  
    21972197 */
    21982198function sanitize_term($term, $taxonomy, $context = 'display') {
    2199 
    22002199    $fields = array( 'term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group', 'term_taxonomy_id', 'object_id' );
    22012200
    … …  
    22362235 *
    22372236 * @since 2.3.0
    2238  *
    2239  * @global wpdb $wpdb WordPress database abstraction object.
    22402237 *
    22412238 * @param string $field    Term field to sanitize.
    … …  
    24042401 * @since 2.3.0
    24052402 *
    2406  * @param string $taxonomy Taxonomy name
    2407  * @param array|string $args Overwrite defaults. See get_terms()
    2408  * @return int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
     2403 * @param string       $taxonomy Taxonomy name
     2404 * @param array|string $args     Overwrite defaults. See get_terms()
     2405 * @return array|int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
    24092406 */
    24102407function wp_count_terms( $taxonomy, $args = array() ) {
    … …  
    24322429 * @since 2.3.0
    24332430 *
    2434  * @param int $object_id The term Object Id that refers to the term.
     2431 * @param int          $object_id The term Object Id that refers to the term.
    24352432 * @param string|array $taxonomies List of Taxonomy Names or single Taxonomy name.
    24362433 */
    … …  
    24692466 * @param string       $taxonomy Taxonomy Name.
    24702467 * @param array|string $args     Optional. Change 'default' term id and override found term ids.
    2471  * @return bool|WP_Error Returns false if not term; true if completes delete action.
     2468 * @return bool|int|WP_Error Returns false if not term; true if completes delete action.
    24722469 */
    24732470function wp_delete_term( $term, $taxonomy, $args = array() ) {
    … …  
    26342631 *
    26352632 * @param int $cat_ID
    2636  * @return mixed Returns true if completes delete action; false if term doesn't exist;
     2633 * @return bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist;
    26372634 *  Zero on attempted deletion of default Category; WP_Error object is also a possibility.
    26382635 */
    … …  
    36333630 * @since 2.5.0
    36343631 *
     3632 * @staticvar bool $_defer
     3633 *
    36353634 * @param bool $defer Optional. Enable if true, disable if false.
    36363635 * @return bool Whether term counting is enabled or disabled.
    … …  
    36603659 * @since 2.3.0
    36613660 *
    3662  * @global wpdb $wpdb WordPress database abstraction object.
     3661 * @staticvar array $_deferred
    36633662 *
    36643663 * @param int|array $terms    The term_taxonomy_id of the terms.
    … …  
    36993698 * @param array  $terms    The term_taxonomy_id of terms to update.
    37003699 * @param string $taxonomy The context of the term.
    3701  * @return bool Always true when complete.
     3700 * @return true Always true when complete.
    37023701 */
    37033702function wp_update_term_count_now( $terms, $taxonomy ) {
    … …  
    37753774 *
    37763775 * @global wpdb $wpdb WordPress database abstraction object.
     3776 * @global bool $_wp_suspend_cache_invalidation
    37773777 *
    37783778 * @param int|array $ids            Single or list of Term IDs.
    … …  
    38443844 * @param int    $id       Term object ID.
    38453845 * @param string $taxonomy Taxonomy name.
    3846  * @return bool|array Empty array if $terms found, but not `$taxonomy`. False if nothing is in cache
     3846 * @return bool|mixed Empty array if $terms found, but not `$taxonomy`. False if nothing is in cache
    38473847 *                    for `$taxonomy` and `$id`.
    38483848 */
    38493849function get_object_term_cache( $id, $taxonomy ) {
    3850     $cache = wp_cache_get($id, "{$taxonomy}_relationships");
    3851     return $cache;
     3850    return wp_cache_get( $id, "{$taxonomy}_relationships" );
    38523851}
    38533852
    … …  
    38663865 * @param string|array $object_ids  Comma-separated list or array of term object IDs.
    38673866 * @param array|string $object_type The taxonomy object type.
    3868  * @return null|false Null if `$object_ids` is empty, false if all of the terms in
    3869  *                    `$object_ids` are already cached.
     3867 * @return void|false False if all of the terms in `$object_ids` are already cached.
    38703868 */
    38713869function update_object_term_cache($object_ids, $object_type) {
    … …  
    39823980 *                          to prevent infinite recursion loops. For performance, `term_ids` are used as array keys,
    39833981 *                          with 1 as value. Default empty array.
    3984  * @return array The subset of $terms that are descendants of $term_id.
     3982 * @return array|WP_Error The subset of $terms that are descendants of $term_id.
    39853983 */
    39863984function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() ) {
    … …  
    40464044 * @param array  $terms    List of term IDs, passed by reference.
    40474045 * @param string $taxonomy Term context.
    4048  * @return null Will break from function if conditions are not met.
    40494046 */
    40504047function _pad_term_counts( &$terms, $taxonomy ) {
    … …  
    41174114 * @global wpdb $wpdb WordPress database abstraction object.
    41184115 *
    4119  * @param array $terms List of Term taxonomy IDs.
     4116 * @param array  $terms    List of Term taxonomy IDs.
    41204117 * @param object $taxonomy Current taxonomy object of terms.
    41214118 */
    … …  
    41664163 * @global wpdb $wpdb WordPress database abstraction object.
    41674164 *
    4168  * @param array $terms List of term taxonomy IDs.
     4165 * @param array  $terms    List of term taxonomy IDs.
    41694166 * @param object $taxonomy Current taxonomy object of terms.
    41704167 */
    … …  
    41894186 * @ignore
    41904187 * @since 4.2.0
     4188 *
     4189 * @global wpdb $wpdb
    41914190 *
    41924191 * @param int  $term_id          ID of the shared term.
    … …  
    43104309 * @ignore
    43114310 * @since 4.2.0
     4311 *
     4312 * @global wpdb $wpdb
    43124313 *
    43134314 * @param int    $term_id          ID of the formerly shared term.
    … …  
    43634364 * @param int    $old_term_id Term ID. This is the old, pre-split term ID.
    43644365 * @param string $taxonomy    Taxonomy that the term belongs to.
    4365  * @return bool|int If a previously split term is found corresponding to the old term_id and taxonomy,
    4366  *                  the new term_id will be returned. If no previously split term is found matching
    4367  *                  the parameters, returns false.
     4366 * @return int|false If a previously split term is found corresponding to the old term_id and taxonomy,
     4367 *                   the new term_id will be returned. If no previously split term is found matching
     4368 *                   the parameters, returns false.
    43684369 */
    43694370function wp_get_split_term( $old_term_id, $taxonomy ) {
    … …  
    43834384 * @since 2.5.0
    43844385 * @since 4.3.0 Introduced `$field` argument.
     4386 *
     4387 * @global WP_Rewrite $wp_rewrite
    43854388 *
    43864389 * @param object|int|string $term     The term object, ID, or slug whose link will be retrieved.
    … …  
    46574660 * @return bool True if object is associated with the taxonomy, otherwise false.
    46584661 */
    4659 function is_object_in_taxonomy($object_type, $taxonomy) {
    4660     $taxonomies = get_object_taxonomies($object_type);
    4661 
    4662     if ( empty($taxonomies) )
     4662function is_object_in_taxonomy( $object_type, $taxonomy ) {
     4663    $taxonomies = get_object_taxonomies( $object_type );
     4664    if ( empty( $taxonomies ) ) {
    46634665        return false;
    4664 
    4665     if ( in_array($taxonomy, $taxonomies) )
    4666         return true;
    4667 
    4668     return false;
     4666    }
     4667    return in_array( $taxonomy, $taxonomies );
    46694668}
    46704669
    … …  
    47324731 * @param int    $term_id  Term ID.
    47334732 * @param string $taxonomy Taxonomy name.
    4734  * @return int|bool False on error.
     4733 * @return int|false False on error.
    47354734 */
    47364735function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) {
    47374736    $term = get_term( $term_id, $taxonomy );
    4738     if ( !$term || is_wp_error( $term ) )
     4737    if ( ! $term || is_wp_error( $term ) ) {
    47394738        return false;
     4739    }
    47404740    return (int) $term->parent;
    47414741}
Note: See TracChangeset for help on using the changeset viewer.