diff --git a/wp-includes/comment.php b/wp-includes/comment.php index f3cdb9cc0f..8eb1c97da5 100644 --- a/wp-includes/comment.php +++ b/wp-includes/comment.php @@ -447,10 +447,11 @@ function get_comment_count( $post_id = 0 ) { * @since 2.9.0 * @link https://developer.wordpress.org/reference/functions/add_comment_meta/ * - * @param int $comment_id Comment ID. - * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. - * @param bool $unique Optional. Whether the same key should not be added. Default false. + * @param int $comment_id Comment ID. + * @param string $meta_key Metadata name. + * @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. * @return int|bool Meta ID on success, false on failure. */ 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 * @link https://developer.wordpress.org/reference/functions/delete_comment_meta/ * - * @param int $comment_id comment ID - * @param string $meta_key Metadata name. - * @param mixed $meta_value Optional. Metadata value. + * @param int $comment_id Comment ID. + * @param string $meta_key Metadata name. + * @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. */ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) { @@ -482,11 +485,14 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) { * @since 2.9.0 * @link https://developer.wordpress.org/reference/functions/get_comment_meta/ * - * @param int $comment_id Comment ID. - * @param string $key Optional. The meta key to retrieve. By default, returns data for all keys. - * @param bool $single Optional. Whether to return a single value. Default false. - * @return mixed Will be an array if $single is false. Will be value of meta data field if $single - * is true. + * @param int $comment_id Comment ID. + * @param string $key Optional. The meta key to retrieve. By default, + * returns data for all keys. + * @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_comment_meta( $comment_id, $key = '', $single = false ) { return get_metadata( 'comment', $comment_id, $key, $single ); @@ -503,11 +509,13 @@ function get_comment_meta( $comment_id, $key = '', $single = false ) { * @since 2.9.0 * @link https://developer.wordpress.org/reference/functions/update_comment_meta/ * - * @param int $comment_id Comment ID. - * @param string $meta_key Metadata key. - * @param mixed $meta_value Metadata value. - * @param mixed $prev_value Optional. Previous value to check before updating. Default empty. - * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. + * @param int $comment_id Comment ID. + * @param string $meta_key Metadata key. + * @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. + * @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 = '' ) { return update_metadata( 'comment', $comment_id, $meta_key, $meta_value, $prev_value ); diff --git a/wp-includes/deprecated.php b/wp-includes/deprecated.php index f4e50a2a1c..12312d6449 100644 --- a/wp-includes/deprecated.php +++ b/wp-includes/deprecated.php @@ -2211,7 +2211,7 @@ function unregister_widget_control($id) { * * @param int $user_id User ID. * @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. */ 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() * * @param int $user_id User ID - * @param string $meta_key Optional. Metadata key. + * @param string $meta_key Optional. Metadata key. Default empty. * @return mixed */ function get_usermeta( $user_id, $meta_key = '' ) { diff --git a/wp-includes/meta.php b/wp-includes/meta.php index 73f253a840..7eee83a759 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -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', * or any other object type with an associated meta table. * @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. * @return bool True on successful update, false on failure. */ diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php index 947f0e0301..d4f9a5f9d0 100644 --- a/wp-includes/ms-site.php +++ b/wp-includes/ms-site.php @@ -385,7 +385,7 @@ function update_site_cache( $sites, $update_meta_cache = true ) { * @since 5.1.0 * * @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 ) { // 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 string $meta_key Metadata name. - * @param mixed $meta_value Optional. Metadata value. Must be serializable if - * non-scalar. Default empty. + * @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. */ 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 * * @param int $site_id Site ID. - * @param string $key Optional. The meta key to retrieve. By default, returns - * data for all keys. Default empty. - * @param bool $single Optional. Whether to return a single value. Default false. - * @return mixed Will be an array if $single is false. Will be value of meta data - * field if $single is true. + * @param string $key Optional. The meta key to retrieve. By default, + * returns data for all keys. Default empty. + * @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_site_meta( $site_id, $key = '', $single = false ) { return get_metadata( 'blog', $site_id, $key, $single ); diff --git a/wp-includes/option.php b/wp-includes/option.php index 156c2ad3f2..b38ea66109 100644 --- a/wp-includes/option.php +++ b/wp-includes/option.php @@ -452,7 +452,8 @@ function update_option( $option, $value, $autoload = null ) { * @global wpdb $wpdb WordPress database abstraction object. * * @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|bool $autoload Optional. Whether to load the option when WordPress starts up. * Default is enabled. Accepts 'no' to disable for legacy reasons. @@ -747,8 +748,8 @@ function get_transient( $transient ) { * * @since 2.8.0 * - * @param string $transient Transient name. Expected to not be SQL-escaped. Must be - * 172 characters or fewer in length. + * @param string $transient Transient name. Expected to not be SQL-escaped. + * Must be 172 characters or fewer in length. * @param mixed $value Transient value. Must be serializable if non-scalar. * Expected to not be SQL-escaped. * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). diff --git a/wp-includes/post.php b/wp-includes/post.php index 262f986221..87de98d0ff 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -2090,8 +2090,9 @@ function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) { * * @param int $post_id Post ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Optional. Metadata value. Must be serializable if - * non-scalar. Default empty. + * @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. */ 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 * * @param int $post_id Post ID. - * @param string $key Optional. The meta key to retrieve. By default, returns - * data for all keys. Default empty. - * @param bool $single Optional. If true, returns only the first value for the specified meta key. - * This parameter has no effect if $key is not specified. Default false. - * @return mixed Will be an array if $single is false. Will be value of the meta - * field if $single is true. + * @param string $key Optional. The meta key to retrieve. By default, + * returns data for all keys. Default empty. + * @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 the meta field + * if $single is true. */ function get_post_meta( $post_id, $key = '', $single = false ) { 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 string $meta_key Metadata key. * @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. - * @return int|bool The new meta field ID if a field with the given key didn't exist and was - * therefore added, true on successful update, false on failure. + * @param mixed $prev_value Optional. Previous value to check before updating. + * Default empty. + * @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 = '' ) { // 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 * * @param int[] $post_ids Array of post IDs. - * @return array|false Returns false if there is nothing to update or an array - * of metadata. + * @return array|false An array of metadata on success, false if there is nothing to update. */ function update_postmeta_cache( $post_ids ) { return update_meta_cache( 'post', $post_ids ); diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 0d257c0e7f..3dc33122d8 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -1211,11 +1211,11 @@ function get_terms( $args = array(), $deprecated = '' ) { * * @param int $term_id Term ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. - * @param bool $unique Optional. Whether to bail if an entry with the same key is found for the term. + * @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. - * @return int|WP_Error|bool Meta ID on success. WP_Error when term_id is ambiguous between taxonomies. - * False on failure. + * @return int|false|WP_Error Meta ID on success, false on failure. + * WP_Error when term_id is ambiguous between taxonomies. */ function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) { 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 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. */ 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 * * @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 bool $single Optional. Whether to return a single value. If false, an array of all values matching the - * `$term_id`/`$key` pair will be returned. Default false. - * @return mixed If `$single` is false, an array of metadata values. If `$single` is true, a single metadata value. + * @param string $key Optional. The meta key to retrieve. By default, + * returns data for all keys. Default empty. + * @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 the meta field + * if $single is true. */ function get_term_meta( $term_id, $key = '', $single = false ) { 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 string $meta_key Metadata key. - * @param mixed $meta_value Metadata value. - * @param mixed $prev_value Optional. Previous value to check before updating. Default empty. - * @return int|WP_Error|bool Meta ID if the key didn't previously exist. True on successful update. - * WP_Error when term_id is ambiguous between taxonomies. False on failure. + * @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. + * @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 = '' ) { 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 * * @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 ) { return update_meta_cache( 'term', $term_ids ); diff --git a/wp-includes/user.php b/wp-includes/user.php index 2223e7a40e..4404a4b90b 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -786,8 +786,9 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) { * * @param int $user_id User ID. * @param string $meta_key Metadata name. - * @param mixed $meta_value Metadata value. - * @param bool $unique Optional. Whether the same key should not be added. Default false. + * @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. * @return int|false Meta ID on success, false on failure. */ 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 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. */ 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/ * * @param int $user_id User ID. - * @param string $key Optional. The meta key to retrieve. By default, returns data for all keys. - * @param bool $single Optional. Whether to return a single value. Default false. - * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true. + * @param string $key Optional. The meta key to retrieve. By default, + * returns data for all keys. + * @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 ) { 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 string $meta_key Metadata key. - * @param mixed $meta_value Metadata value. - * @param mixed $prev_value Optional. Previous value to check before updating. Default empty. - * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. + * @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. + * @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 = '' ) { return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value ); diff --git a/wp-includes/version.php b/wp-includes/version.php index b814c6c17d..3a34aed8f4 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @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.