WordPress.org
Get WordPress

Make WordPress Core

Changeset 48192


Ignore:
Timestamp:
06/27/2020 04:32:57 PM (6 years ago)
Author:
johnbillion
Message:

Docs: Improvements to the inline docs for metadata related functions.

See #49572.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r48121 r48192  
    5555
    5656        /**
    57          * Filters whether to add metadata of a specific type.
     57         * Short-circuits adding metadata of a specific type.
    5858         *
    5959         * The dynamic portion of the hook, `$meta_type`, refers to the meta
    … …  
    184184
    185185        /**
    186          * Filters whether to update metadata of a specific type.
     186         * Short-circuits updating metadata of a specific type.
    187187         *
    188188         * The dynamic portion of the hook, `$meta_type`, refers to the meta
    … …  
    354354
    355355        /**
    356          * Filters whether to delete metadata of a specific type.
     356         * Short-circuits deleting metadata of a specific type.
    357357         *
    358358         * The dynamic portion of the hook, `$meta_type`, refers to the meta
    … …  
    475475
    476476/**
    477  * Retrieves metadata for the specified object.
     477 * Retrieves the value of a metadata field for the specified object type and ID.
     478 *
     479 * If the meta field exists, a single value is returned if `$single` is true, or an array of values if it's false.
     480 * If the meta field does not exist, an empty string is returned if `$single` is true, or an empty array if it's false.
     481 * If there's a problem with the parameters passed to the function, boolean `false` is returned.
    478482 *
    479483 * @since 2.9.0
    … …  
    486490 * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
    487491 *                          This parameter has no effect if meta_key is not specified. Default false.
    488  * @return mixed Single metadata value, or array of values
     492 * @return mixed The metadata value or array of values. See description above for further details.
    489493 */
    490494function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
    … …  
    499503
    500504        /**
    501          * Filters whether to retrieve metadata of a specific type.
    502          *
    503          * The dynamic portion of the hook, `$meta_type`, refers to the meta
     505         * Short-circuits the return value of a meta field.
     506         *
     507         * The dynamic portion of the hook name, `$meta_type`, refers to the
    504508         * object type (comment, post, term, or user). Returning a non-null value
    505          * will effectively short-circuit the function.
     509         * will short-circuit the return value.
    506510         *
    507511         * @since 3.1.0
    508512         *
    509          * @param null|array|string $value     The value get_metadata() should return - a single metadata value,
    510          *                                     or an array of values.
    511          * @param int               $object_id ID of the object metadata is for.
    512          * @param string            $meta_key  Metadata key.
    513          * @param bool              $single    Whether to return only the first value of the specified $meta_key.
     513         * @param mixed  $value     The value to return, either a single metadata value or an array
     514         *                          of values depending on the value of `$single`. Default null.
     515         * @param int    $object_id ID of the object metadata is for.
     516         * @param string $meta_key  Metadata key.
     517         * @param bool   $single    Whether to return only the first value of the specified $meta_key.
    514518         */
    515519        $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
    … …  
    553557
    554558/**
    555  * Determines if a meta key is set for a given object.
     559 * Determines if a meta field with the given key exists for the given object ID.
    556560 *
    557561 * @since 3.3.0
    … …  
    561565 * @param int    $object_id ID of the object metadata is for.
    562566 * @param string $meta_key  Metadata key.
    563  * @return bool True of the key is set, false if not.
     567 * @return bool Whether a meta field with the given key exists.
    564568 */
    565569function metadata_exists( $meta_type, $object_id, $meta_key ) {
    … …  
    603607 *                          or any other object type with an associated meta table.
    604608 * @param int    $meta_id   ID for a specific meta row.
    605  * @return object|false Meta object or false.
     609 * @return stdClass|false {
     610 *     Metadata object, or boolean `false` if the metadata doesn't exist.
     611 *
     612 *     @type string $meta_key   The meta key.
     613 *     @type mixed  $meta_value The unserialized meta value.
     614 *     @type string $meta_id    Optional. The meta ID when the meta type is any value except 'user'.
     615 *     @type string $umeta_id   Optional. The meta ID when the meta type is 'user'.
     616 *     @type string $post_id    Optional. The object ID when the meta type is 'post'.
     617 *     @type string $comment_id Optional. The object ID when the meta type is 'comment'.
     618 *     @type string $term_id    Optional. The object ID when the meta type is 'term'.
     619 *     @type string $user_id    Optional. The object ID when the meta type is 'user'.
     620 * }
    606621 */
    607622function get_metadata_by_mid( $meta_type, $meta_id ) {
    … …  
    625640
    626641        /**
    627          * Filters whether to retrieve metadata of a specific type by meta ID.
    628          *
    629          * The dynamic portion of the hook, `$meta_type`, refers to the meta
     642         * Short-circuits the return value when fetching a meta field by meta ID.
     643         *
     644         * The dynamic portion of the hook name, `$meta_type`, refers to the
    630645         * object type (comment, post, term, or user). Returning a non-null value
    631          * will effectively short-circuit the function.
     646         * will short-circuit the return value.
    632647         *
    633648         * @since 5.0.0
    634649         *
    635          * @param mixed $value    The value get_metadata_by_mid() should return.
    636          * @param int   $meta_id Meta ID.
     650         * @param stdClass|null $value   The value to return.
     651         * @param int           $meta_id Meta ID.
    637652         */
    638653        $check = apply_filters( "get_{$meta_type}_metadata_by_mid", null, $meta_id );
    … …  
    690705
    691706        /**
    692          * Filters whether to update metadata of a specific type by meta ID.
     707         * Short-circuits updating metadata of a specific type by meta ID.
    693708         *
    694709         * The dynamic portion of the hook, `$meta_type`, refers to the meta
    … …  
    806821
    807822        /**
    808          * Filters whether to delete metadata of a specific type by meta ID.
     823         * Short-circuits deleting metadata of a specific type by meta ID.
    809824         *
    810825         * The dynamic portion of the hook, `$meta_type`, refers to the meta
    … …  
    911926
    912927        /**
    913          * Filters whether to update the metadata cache of a specific type.
     928         * Short-circuits updating the metadata cache of a specific type.
    914929         *
    915930         * The dynamic portion of the hook, `$meta_type`, refers to the meta
Note: See TracChangeset for help on using the changeset viewer.