WordPress.org
Get WordPress

Make WordPress Core

Changeset 48192


Ignore:
Timestamp:
06/27/2020 04:32:57 PM (4 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.