WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

See #49572.
Built from https://develop.svn.wordpress.org/trunk@47611


git-svn-id: http://core.svn.wordpress.org/trunk@47386 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2020-04-22 10:31:09 +00:00
parent 9aa0fff80e
commit 427405535f
9 changed files with 98 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
wp-includes/comment.php
View File

@ -449,8 +449,9 @@ function get_comment_count( $post_id = 0 ) {
* *
* @param int $comment_id Comment ID. * @param int $comment_id Comment ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. Whether the same key should not be added. Default false. * @param bool $unique Optional. Whether the same key should not be added.
* Default false.
* @return int|bool Meta ID on success, false on failure. * @return int|bool Meta ID on success, false on failure.
*/ */
function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false ) { function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false ) {
@ -467,9 +468,11 @@ function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false
* @since 2.9.0 * @since 2.9.0
* @link https://developer.wordpress.org/reference/functions/delete_comment_meta/ * @link https://developer.wordpress.org/reference/functions/delete_comment_meta/
* *
* @param int $comment_id comment ID * @param int $comment_id Comment ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. * @param mixed $meta_value Optional. Metadata value. If provided,
* rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) { function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
@ -483,10 +486,13 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
* @link https://developer.wordpress.org/reference/functions/get_comment_meta/ * @link https://developer.wordpress.org/reference/functions/get_comment_meta/
* *
* @param int $comment_id Comment ID. * @param int $comment_id Comment ID.
* @param string $key Optional. The meta key to retrieve. By default, returns data for all keys. * @param string $key Optional. The meta key to retrieve. By default,
* @param bool $single Optional. Whether to return a single value. Default false. * returns data for all keys.
* @return mixed Will be an array if $single is false. Will be value of meta data field if $single * @param bool $single Optional. Whether to return a single value.
* is true. * This parameter has no effect if $key is not specified.
* Default false.
* @return mixed An array if $single is false. The value of meta data field
* if $single is true.
*/ */
function get_comment_meta( $comment_id, $key = '', $single = false ) { function get_comment_meta( $comment_id, $key = '', $single = false ) {
return get_metadata( 'comment', $comment_id, $key, $single ); return get_metadata( 'comment', $comment_id, $key, $single );
@ -505,9 +511,11 @@ function get_comment_meta( $comment_id, $key = '', $single = false ) {
* *
* @param int $comment_id Comment ID. * @param int $comment_id Comment ID.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating. Default empty. * @param mixed $prev_value Optional. Previous value to check before updating.
* @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. * Default empty.
* @return int|bool Meta ID if the key didn't exist, true on successful update,
* false on failure.
*/ */
function update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' ) { function update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' ) {
return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value ); return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value );

4
wp-includes/deprecated.php
View File

@ -2211,7 +2211,7 @@ function unregister_widget_control($id) {
* *
* @param int $user_id User ID. * @param int $user_id User ID.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Optional. Metadata value. Default empty.
* @return bool True deletion completed and false if user_id is not a number. * @return bool True deletion completed and false if user_id is not a number.
*/ */
function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) { function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
@ -2257,7 +2257,7 @@ function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
* @see get_user_meta() * @see get_user_meta()
* *
* @param int $user_id User ID * @param int $user_id User ID
* @param string $meta_key Optional. Metadata key. * @param string $meta_key Optional. Metadata key. Default empty.
* @return mixed * @return mixed
*/ */
function get_usermeta( $user_id, $meta_key = '' ) { function get_usermeta( $user_id, $meta_key = '' ) {

2
wp-includes/meta.php
View File

@ -662,7 +662,7 @@ function get_metadata_by_mid( $meta_type, $meta_id ) {
* @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table. * or any other object type with an associated meta table.
* @param int $meta_id ID for a specific meta row. * @param int $meta_id ID for a specific meta row.
* @param string $meta_value Metadata value. * @param string $meta_value Metadata value. Must be serializable if non-scalar.
* @param string $meta_key Optional. You can provide a meta key to update it. Default false. * @param string $meta_key Optional. You can provide a meta key to update it. Default false.
* @return bool True on successful update, false on failure. * @return bool True on successful update, false on failure.
*/ */

19
wp-includes/ms-site.php
View File

@ -385,7 +385,7 @@ function update_site_cache( $sites, $update_meta_cache = true ) {
* @since 5.1.0 * @since 5.1.0
* *
* @param array $site_ids List of site IDs. * @param array $site_ids List of site IDs.
* @return array|false Returns false if there is nothing to update. Returns an array of metadata on success. * @return array|false An array of metadata on success, false if there is nothing to update.
*/ */
function update_sitemeta_cache( $site_ids ) { function update_sitemeta_cache( $site_ids ) {
// Ensure this filter is hooked in even if the function is called early. // Ensure this filter is hooked in even if the function is called early.
@ -1059,8 +1059,9 @@ function add_site_meta( $site_id, $meta_key, $meta_value, $unique = false ) {
* *
* @param int $site_id Site ID. * @param int $site_id Site ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. Must be serializable if * @param mixed $meta_value Optional. Metadata value. If provided,
* non-scalar. Default empty. * rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
function delete_site_meta( $site_id, $meta_key, $meta_value = '' ) { function delete_site_meta( $site_id, $meta_key, $meta_value = '' ) {
@ -1073,11 +1074,13 @@ function delete_site_meta( $site_id, $meta_key, $meta_value = '' ) {
* @since 5.1.0 * @since 5.1.0
* *
* @param int $site_id Site ID. * @param int $site_id Site ID.
* @param string $key Optional. The meta key to retrieve. By default, returns * @param string $key Optional. The meta key to retrieve. By default,
* data for all keys. Default empty. * returns data for all keys. Default empty.
* @param bool $single Optional. Whether to return a single value. Default false. * @param bool $single Optional. Whether to return a single value.
* @return mixed Will be an array if $single is false. Will be value of meta data * This parameter has no effect if $key is not specified.
* field if $single is true. * Default false.
* @return mixed An array if $single is false. The value of meta data field
* if $single is true.
*/ */
function get_site_meta( $site_id, $key = '', $single = false ) { function get_site_meta( $site_id, $key = '', $single = false ) {
return get_metadata( 'blog', $site_id, $key, $single ); return get_metadata( 'blog', $site_id, $key, $single );

7
wp-includes/option.php
View File

@ -452,7 +452,8 @@ function update_option( $option, $value, $autoload = null ) {
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $option Name of option to add. Expected to not be SQL-escaped. * @param string $option Name of option to add. Expected to not be SQL-escaped.
* @param mixed $value Optional. Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped. * @param mixed $value Optional. Option value. Must be serializable if non-scalar.
* Expected to not be SQL-escaped.
* @param string $deprecated Optional. Description. Not used anymore. * @param string $deprecated Optional. Description. Not used anymore.
* @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up.
* Default is enabled. Accepts 'no' to disable for legacy reasons. * Default is enabled. Accepts 'no' to disable for legacy reasons.
@ -747,8 +748,8 @@ function get_transient( $transient ) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $transient Transient name. Expected to not be SQL-escaped. Must be * @param string $transient Transient name. Expected to not be SQL-escaped.
* 172 characters or fewer in length. * Must be 172 characters or fewer in length.
* @param mixed $value Transient value. Must be serializable if non-scalar. * @param mixed $value Transient value. Must be serializable if non-scalar.
* Expected to not be SQL-escaped. * Expected to not be SQL-escaped.
* @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration).

28
wp-includes/post.php
View File

@ -2090,8 +2090,9 @@ function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
* *
* @param int $post_id Post ID. * @param int $post_id Post ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. Must be serializable if * @param mixed $meta_value Optional. Metadata value. If provided,
* non-scalar. Default empty. * rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) { function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
@ -2110,12 +2111,13 @@ function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
* @since 1.5.0 * @since 1.5.0
* *
* @param int $post_id Post ID. * @param int $post_id Post ID.
* @param string $key Optional. The meta key to retrieve. By default, returns * @param string $key Optional. The meta key to retrieve. By default,
* data for all keys. Default empty. * returns data for all keys. Default empty.
* @param bool $single Optional. If true, returns only the first value for the specified meta key. * @param bool $single Optional. Whether to return a single value.
* This parameter has no effect if $key is not specified. Default false. * This parameter has no effect if $key is not specified.
* @return mixed Will be an array if $single is false. Will be value of the meta * Default false.
* field if $single is true. * @return mixed An array if $single is false. The value of the meta field
* if $single is true.
*/ */
function get_post_meta( $post_id, $key = '', $single = false ) { function get_post_meta( $post_id, $key = '', $single = false ) {
return get_metadata( 'post', $post_id, $key, $single ); return get_metadata( 'post', $post_id, $key, $single );
@ -2136,9 +2138,10 @@ function get_post_meta( $post_id, $key = '', $single = false ) {
* @param int $post_id Post ID. * @param int $post_id Post ID.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating. Default empty. * @param mixed $prev_value Optional. Previous value to check before updating.
* @return int|bool The new meta field ID if a field with the given key didn't exist and was * Default empty.
* therefore added, true on successful update, false on failure. * @return int|bool Meta ID if the key didn't exist, true on successful update,
* false on failure.
*/ */
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) { function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
// Make sure meta is added to the post, not a revision. // Make sure meta is added to the post, not a revision.
@ -6766,8 +6769,7 @@ function update_post_caches( &$posts, $post_type = 'post', $update_term_cache =
* @since 2.1.0 * @since 2.1.0
* *
* @param int[] $post_ids Array of post IDs. * @param int[] $post_ids Array of post IDs.
* @return array|false Returns false if there is nothing to update or an array * @return array|false An array of metadata on success, false if there is nothing to update.
* of metadata.
*/ */
function update_postmeta_cache( $post_ids ) { function update_postmeta_cache( $post_ids ) {
return update_meta_cache( 'post', $post_ids ); return update_meta_cache( 'post', $post_ids );

35
wp-includes/taxonomy.php
View File

@ -1211,11 +1211,11 @@ function get_terms( $args = array(), $deprecated = '' ) {
* *
* @param int $term_id Term ID. * @param int $term_id Term ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. Whether to bail if an entry with the same key is found for the term. * @param bool $unique Optional. Whether the same key should not be added.
* Default false. * Default false.
* @return int|WP_Error|bool Meta ID on success. WP_Error when term_id is ambiguous between taxonomies. * @return int|false|WP_Error Meta ID on success, false on failure.
* False on failure. * WP_Error when term_id is ambiguous between taxonomies.
*/ */
function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) { function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) {
if ( wp_term_is_shared( $term_id ) ) { if ( wp_term_is_shared( $term_id ) ) {
@ -1232,7 +1232,9 @@ function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) {
* *
* @param int $term_id Term ID. * @param int $term_id Term ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. If provided, rows will only be removed that match the value. * @param mixed $meta_value Optional. Metadata value. If provided,
* rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) { function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) {
@ -1245,10 +1247,13 @@ function delete_term_meta( $term_id, $meta_key, $meta_value = '' ) {
* @since 4.4.0 * @since 4.4.0
* *
* @param int $term_id Term ID. * @param int $term_id Term ID.
* @param string $key Optional. The meta key to retrieve. If no key is provided, fetches all metadata for the term. * @param string $key Optional. The meta key to retrieve. By default,
* @param bool $single Optional. Whether to return a single value. If false, an array of all values matching the * returns data for all keys. Default empty.
* `$term_id`/`$key` pair will be returned. Default false. * @param bool $single Optional. Whether to return a single value.
* @return mixed If `$single` is false, an array of metadata values. If `$single` is true, a single metadata value. * This parameter has no effect if $key is not specified.
* Default false.
* @return mixed An array if $single is false. The value of the meta field
* if $single is true.
*/ */
function get_term_meta( $term_id, $key = '', $single = false ) { function get_term_meta( $term_id, $key = '', $single = false ) {
return get_metadata( 'term', $term_id, $key, $single ); return get_metadata( 'term', $term_id, $key, $single );
@ -1265,10 +1270,12 @@ function get_term_meta( $term_id, $key = '', $single = false ) {
* *
* @param int $term_id Term ID. * @param int $term_id Term ID.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating. Default empty. * @param mixed $prev_value Optional. Previous value to check before updating.
* @return int|WP_Error|bool Meta ID if the key didn't previously exist. True on successful update. * Default empty.
* WP_Error when term_id is ambiguous between taxonomies. False on failure. * @return int|bool|WP_Error Meta ID if the key didn't exist. true on successful update,
* false on failure. WP_Error when term_id is ambiguous
* between taxonomies.
*/ */
function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) { function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' ) {
if ( wp_term_is_shared( $term_id ) ) { if ( wp_term_is_shared( $term_id ) ) {
@ -1287,7 +1294,7 @@ function update_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' )
* @since 4.4.0 * @since 4.4.0
* *
* @param array $term_ids List of term IDs. * @param array $term_ids List of term IDs.
* @return array|false Returns false if there is nothing to update. Returns an array of metadata on success. * @return array|false An array of metadata on success, false if there is nothing to update.
*/ */
function update_termmeta_cache( $term_ids ) { function update_termmeta_cache( $term_ids ) {
return update_meta_cache( 'term', $term_ids ); return update_meta_cache( 'term', $term_ids );

27
wp-includes/user.php
View File

@ -786,8 +786,9 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) {
* *
* @param int $user_id User ID. * @param int $user_id User ID.
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. Whether the same key should not be added. Default false. * @param bool $unique Optional. Whether the same key should not be added.
* Default false.
* @return int|false Meta ID on success, false on failure. * @return int|false Meta ID on success, false on failure.
*/ */
function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) { function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) {
@ -806,7 +807,9 @@ function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) {
* *
* @param int $user_id User ID * @param int $user_id User ID
* @param string $meta_key Metadata name. * @param string $meta_key Metadata name.
* @param mixed $meta_value Optional. Metadata value. * @param mixed $meta_value Optional. Metadata value. If provided,
* rows will only be removed that match the value.
* Must be serializable if non-scalar. Default empty.
* @return bool True on success, false on failure. * @return bool True on success, false on failure.
*/ */
function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) { function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) {
@ -820,9 +823,13 @@ function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) {
* @link https://developer.wordpress.org/reference/functions/get_user_meta/ * @link https://developer.wordpress.org/reference/functions/get_user_meta/
* *
* @param int $user_id User ID. * @param int $user_id User ID.
* @param string $key Optional. The meta key to retrieve. By default, returns data for all keys. * @param string $key Optional. The meta key to retrieve. By default,
* @param bool $single Optional. Whether to return a single value. Default false. * returns data for all keys.
* @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true. * @param bool $single Optional. Whether to return a single value.
* This parameter has no effect if $key is not specified.
* Default false.
* @return mixed An array if $single is false. The value of meta data field
* if $single is true.
*/ */
function get_user_meta( $user_id, $key = '', $single = false ) { function get_user_meta( $user_id, $key = '', $single = false ) {
return get_metadata( 'user', $user_id, $key, $single ); return get_metadata( 'user', $user_id, $key, $single );
@ -841,9 +848,11 @@ function get_user_meta( $user_id, $key = '', $single = false ) {
* *
* @param int $user_id User ID. * @param int $user_id User ID.
* @param string $meta_key Metadata key. * @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before updating. Default empty. * @param mixed $prev_value Optional. Previous value to check before updating.
* @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. * Default empty.
* @return int|bool Meta ID if the key didn't exist, true on successful update,
* false on failure.
*/ */
function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) { function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value ); return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '5.5-alpha-47610'; $wp_version = '5.5-alpha-47611';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.