WordPress.org

Make WordPress Core

Changeset 47611


Ignore:
Timestamp:
04/22/2020 10:29:34 AM (4 months ago)
Author:
SergeyBiryukov
Message:

Docs: Synchronize parameter documentation for various metadata functions, update per the documentation standards.

See #49572.

Location:
trunk/src/wp-includes
Files:
8 edited

Legend:

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

    r47610 r47611  
    448448 * @link https://developer.wordpress.org/reference/functions/add_comment_meta/
    449449 *
    450  * @param int $comment_id Comment ID.
    451  * @param string $meta_key Metadata name.
    452  * @param mixed $meta_value Metadata value.
    453  * @param bool $unique Optional. Whether the same key should not be added. Default false.
     450 * @param int    $comment_id Comment ID.
     451 * @param string $meta_key   Metadata name.
     452 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     453 * @param bool   $unique     Optional. Whether the same key should not be added.
     454 *                           Default false.
    454455 * @return int|bool Meta ID on success, false on failure.
    455456 */
     
    468469 * @link https://developer.wordpress.org/reference/functions/delete_comment_meta/
    469470 *
    470  * @param int $comment_id comment ID
    471  * @param string $meta_key Metadata name.
    472  * @param mixed $meta_value Optional. Metadata value.
     471 * @param int    $comment_id Comment ID.
     472 * @param string $meta_key   Metadata name.
     473 * @param mixed  $meta_value Optional. Metadata value. If provided,
     474 *                           rows will only be removed that match the value.
     475 *                           Must be serializable if non-scalar. Default empty.
    473476 * @return bool True on success, false on failure.
    474477 */
     
    483486 * @link https://developer.wordpress.org/reference/functions/get_comment_meta/
    484487 *
    485  * @param int $comment_id Comment ID.
    486  * @param string $key Optional. The meta key to retrieve. By default, returns data for all keys.
    487  * @param bool $single Optional. Whether to return a single value. Default false.
    488  * @return mixed Will be an array if $single is false. Will be value of meta data field if $single
    489  *  is true.
     488 * @param int    $comment_id Comment ID.
     489 * @param string $key        Optional. The meta key to retrieve. By default,
     490 *                           returns data for all keys.
     491 * @param bool   $single     Optional. Whether to return a single value.
     492 *                           This parameter has no effect if $key is not specified.
     493 *                           Default false.
     494 * @return mixed An array if $single is false. The value of meta data field
     495 *               if $single is true.
    490496 */
    491497function get_comment_meta( $comment_id, $key = '', $single = false ) {
     
    504510 * @link https://developer.wordpress.org/reference/functions/update_comment_meta/
    505511 *
    506  * @param int $comment_id Comment ID.
    507  * @param string $meta_key Metadata key.
    508  * @param mixed $meta_value Metadata value.
    509  * @param mixed $prev_value Optional. Previous value to check before updating. Default empty.
    510  * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
     512 * @param int    $comment_id Comment ID.
     513 * @param string $meta_key   Metadata key.
     514 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     515 * @param mixed  $prev_value Optional. Previous value to check before updating.
     516 *                           Default empty.
     517 * @return int|bool Meta ID if the key didn't exist, true on successful update,
     518 *                  false on failure.
    511519 */
    512520function update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' ) {
  • trunk/src/wp-includes/deprecated.php

    r47555 r47611  
    22122212 * @param int $user_id User ID.
    22132213 * @param string $meta_key Metadata key.
    2214  * @param mixed $meta_value Metadata value.
     2214 * @param mixed $meta_value Optional. Metadata value. Default empty.
    22152215 * @return bool True deletion completed and false if user_id is not a number.
    22162216 */
     
    22582258 *
    22592259 * @param int $user_id User ID
    2260  * @param string $meta_key Optional. Metadata key.
     2260 * @param string $meta_key Optional. Metadata key. Default empty.
    22612261 * @return mixed
    22622262 */
  • trunk/src/wp-includes/meta.php

    r47610 r47611  
    663663 *                           or any other object type with an associated meta table.
    664664 * @param int    $meta_id    ID for a specific meta row.
    665  * @param string $meta_value Metadata value.
     665 * @param string $meta_value Metadata value. Must be serializable if non-scalar.
    666666 * @param string $meta_key   Optional. You can provide a meta key to update it. Default false.
    667667 * @return bool True on successful update, false on failure.
  • trunk/src/wp-includes/ms-site.php

    r47610 r47611  
    386386 *
    387387 * @param array $site_ids List of site IDs.
    388  * @return array|false Returns false if there is nothing to update. Returns an array of metadata on success.
     388 * @return array|false An array of metadata on success, false if there is nothing to update.
    389389 */
    390390function update_sitemeta_cache( $site_ids ) {
     
    10601060 * @param int    $site_id    Site ID.
    10611061 * @param string $meta_key   Metadata name.
    1062  * @param mixed  $meta_value Optional. Metadata value. Must be serializable if
    1063  *                           non-scalar. Default empty.
     1062 * @param mixed  $meta_value Optional. Metadata value. If provided,
     1063 *                           rows will only be removed that match the value.
     1064 *                           Must be serializable if non-scalar. Default empty.
    10641065 * @return bool True on success, false on failure.
    10651066 */
     
    10741075 *
    10751076 * @param int    $site_id Site ID.
    1076  * @param string $key     Optional. The meta key to retrieve. By default, returns
    1077  *                        data for all keys. Default empty.
    1078  * @param bool   $single  Optional. Whether to return a single value. Default false.
    1079  * @return mixed Will be an array if $single is false. Will be value of meta data
    1080  *               field if $single is true.
     1077 * @param string $key     Optional. The meta key to retrieve. By default,
     1078 *                        returns data for all keys. Default empty.
     1079 * @param bool   $single  Optional. Whether to return a single value.
     1080 *                        This parameter has no effect if $key is not specified.
     1081 *                        Default false.
     1082 * @return mixed An array if $single is false. The value of meta data field
     1083 *               if $single is true.
    10811084 */
    10821085function get_site_meta( $site_id, $key = '', $single = false ) {
  • trunk/src/wp-includes/option.php

    r47550 r47611  
    453453 *
    454454 * @param string         $option      Name of option to add. Expected to not be SQL-escaped.
    455  * @param mixed          $value       Optional. Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
     455 * @param mixed          $value       Optional. Option value. Must be serializable if non-scalar.
     456 *                                    Expected to not be SQL-escaped.
    456457 * @param string         $deprecated  Optional. Description. Not used anymore.
    457458 * @param string|bool    $autoload    Optional. Whether to load the option when WordPress starts up.
     
    748749 * @since 2.8.0
    749750 *
    750  * @param string $transient  Transient name. Expected to not be SQL-escaped. Must be
    751  *                           172 characters or fewer in length.
     751 * @param string $transient  Transient name. Expected to not be SQL-escaped.
     752 *                           Must be 172 characters or fewer in length.
    752753 * @param mixed  $value      Transient value. Must be serializable if non-scalar.
    753754 *                           Expected to not be SQL-escaped.
  • trunk/src/wp-includes/post.php

    r47610 r47611  
    20912091 * @param int    $post_id    Post ID.
    20922092 * @param string $meta_key   Metadata name.
    2093  * @param mixed  $meta_value Optional. Metadata value. Must be serializable if
    2094  *                           non-scalar. Default empty.
     2093 * @param mixed  $meta_value Optional. Metadata value. If provided,
     2094 *                           rows will only be removed that match the value.
     2095 *                           Must be serializable if non-scalar. Default empty.
    20952096 * @return bool True on success, false on failure.
    20962097 */
     
    21112112 *
    21122113 * @param int    $post_id Post ID.
    2113  * @param string $key     Optional. The meta key to retrieve. By default, returns
    2114  *                        data for all keys. Default empty.
    2115  * @param bool   $single  Optional. If true, returns only the first value for the specified meta key.
    2116  *                        This parameter has no effect if $key is not specified. Default false.
    2117  * @return mixed Will be an array if $single is false. Will be value of the meta
    2118  *               field if $single is true.
     2114 * @param string $key     Optional. The meta key to retrieve. By default,
     2115 *                        returns data for all keys. Default empty.
     2116 * @param bool   $single  Optional. Whether to return a single value.
     2117 *                        This parameter has no effect if $key is not specified.
     2118 *                        Default false.
     2119 * @return mixed An array if $single is false. The value of the meta field
     2120 *               if $single is true.
    21192121 */
    21202122function get_post_meta( $post_id, $key = '', $single = false ) {
     
    21372139 * @param string $meta_key   Metadata key.
    21382140 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
    2139  * @param mixed  $prev_value Optional. Previous value to check before updating. Default empty.
    2140  * @return int|bool The new meta field ID if a field with the given key didn't exist and was
    2141  *                  therefore added, true on successful update, false on failure.
     2141 * @param mixed  $prev_value Optional. Previous value to check before updating.
     2142 *                           Default empty.
     2143 * @return int|bool Meta ID if the key didn't exist, true on successful update,
     2144 *                  false on failure.
    21422145 */
    21432146function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
     
    67676770 *
    67686771 * @param int[] $post_ids Array of post IDs.
    6769  * @return array|false Returns false if there is nothing to update or an array
    6770  *                     of metadata.
     6772 * @return array|false An array of metadata on success, false if there is nothing to update.
    67716773 */
    67726774function update_postmeta_cache( $post_ids ) {
  • trunk/src/wp-includes/taxonomy.php

    r47610 r47611  
    12121212 * @param int    $term_id    Term ID.
    12131213 * @param string $meta_key   Metadata name.
    1214  * @param mixed  $meta_value Metadata value.
    1215  * @param bool   $unique     Optional. Whether to bail if an entry with the same key is found for the term.
     1214 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     1215 * @param bool   $unique     Optional. Whether the same key should not be added.
    12161216 *                           Default false.
    1217  * @return int|WP_Error|bool Meta ID on success. WP_Error when term_id is ambiguous between taxonomies.
    1218  *                           False on failure.
     1217 * @return int|false|WP_Error Meta ID on success, false on failure.
     1218 *                            WP_Error when term_id is ambiguous between taxonomies.
    12191219 */
    12201220function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) {
     
    12331233 * @param int    $term_id    Term ID.
    12341234 * @param string $meta_key   Metadata name.
    1235  * @param mixed  $meta_value Optional. Metadata value. If provided, rows will only be removed that match the value.
     1235 * @param mixed  $meta_value Optional. Metadata value. If provided,
     1236 *                           rows will only be removed that match the value.
     1237 *                           Must be serializable if non-scalar. Default empty.
    12361238 * @return bool True on success, false on failure.
    12371239 */
     
    12461248 *
    12471249 * @param int    $term_id Term ID.
    1248  * @param string $key     Optional. The meta key to retrieve. If no key is provided, fetches all metadata for the term.
    1249  * @param bool   $single  Optional. Whether to return a single value. If false, an array of all values matching the
    1250  *                        `$term_id`/`$key` pair will be returned. Default false.
    1251  * @return mixed If `$single` is false, an array of metadata values. If `$single` is true, a single metadata value.
     1250 * @param string $key     Optional. The meta key to retrieve. By default,
     1251 *                        returns data for all keys. Default empty.
     1252 * @param bool   $single  Optional. Whether to return a single value.
     1253 *                        This parameter has no effect if $key is not specified.
     1254 *                        Default false.
     1255 * @return mixed An array if $single is false. The value of the meta field
     1256 *               if $single is true.
    12521257 */
    12531258function get_term_meta( $term_id, $key = '', $single = false ) {
     
    12661271 * @param int    $term_id    Term ID.
    12671272 * @param string $meta_key   Metadata key.
    1268  * @param mixed  $meta_value Metadata value.
    1269  * @param mixed  $prev_value Optional. Previous value to check before updating. Default empty.
    1270  * @return int|WP_Error|bool Meta ID if the key didn't previously exist. True on successful update.
    1271  *                           WP_Error when term_id is ambiguous between taxonomies. False on failure.
     1273 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     1274 * @param mixed  $prev_value Optional. Previous value to check before updating.
     1275 *                           Default empty.
     1276 * @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
     1277 *                           false on failure. WP_Error when term_id is ambiguous
     1278 *                           between taxonomies.
    12721279 */
    12731280function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) {
     
    12881295 *
    12891296 * @param array $term_ids List of term IDs.
    1290  * @return array|false Returns false if there is nothing to update. Returns an array of metadata on success.
     1297 * @return array|false An array of metadata on success, false if there is nothing to update.
    12911298 */
    12921299function update_termmeta_cache( $term_ids ) {
  • trunk/src/wp-includes/user.php

    r47610 r47611  
    787787 * @param int    $user_id    User ID.
    788788 * @param string $meta_key   Metadata name.
    789  * @param mixed  $meta_value Metadata value.
    790  * @param bool   $unique     Optional. Whether the same key should not be added. Default false.
     789 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     790 * @param bool   $unique     Optional. Whether the same key should not be added.
     791 *                           Default false.
    791792 * @return int|false Meta ID on success, false on failure.
    792793 */
     
    807808 * @param int    $user_id    User ID
    808809 * @param string $meta_key   Metadata name.
    809  * @param mixed  $meta_value Optional. Metadata value.
     810 * @param mixed  $meta_value Optional. Metadata value. If provided,
     811 *                           rows will only be removed that match the value.
     812 *                           Must be serializable if non-scalar. Default empty.
    810813 * @return bool True on success, false on failure.
    811814 */
     
    821824 *
    822825 * @param int    $user_id User ID.
    823  * @param string $key     Optional. The meta key to retrieve. By default, returns data for all keys.
    824  * @param bool   $single  Optional. Whether to return a single value. Default false.
    825  * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true.
     826 * @param string $key     Optional. The meta key to retrieve. By default,
     827 *                        returns data for all keys.
     828 * @param bool   $single  Optional. Whether to return a single value.
     829 *                        This parameter has no effect if $key is not specified.
     830 *                        Default false.
     831 * @return mixed An array if $single is false. The value of meta data field
     832 *               if $single is true.
    826833 */
    827834function get_user_meta( $user_id, $key = '', $single = false ) {
     
    842849 * @param int    $user_id    User ID.
    843850 * @param string $meta_key   Metadata key.
    844  * @param mixed  $meta_value Metadata value.
    845  * @param mixed  $prev_value Optional. Previous value to check before updating. Default empty.
    846  * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
     851 * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     852 * @param mixed  $prev_value Optional. Previous value to check before updating.
     853 *                           Default empty.
     854 * @return int|bool Meta ID if the key didn't exist, true on successful update,
     855 *                  false on failure.
    847856 */
    848857function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
Note: See TracChangeset for help on using the changeset viewer.