Changeset 50641 for trunk/src/wp-includes/meta.php

Timestamp:

04/02/2021 03:47:34 PM (4 years ago)

Author:

davidbaumwald

Message:

Docs: Clarify return results for a non-existing ID in metadata functions.

[48658] documented that various metadata functions return false for an invalid ID. However, that does not clarify what an invalid ID is: a non-numeric, zero, or negative value. This change adds the clarification in all relevant metadata function docblocks.

Props icopydoc, SergeyBiryukov, davidkryzaniak, audrasjb.
Fixes #51797.

File:

• trunk/src/wp-includes/meta.php (modified) (4 diffs)

trunk/src/wp-includes/meta.php

@@ -498 +498 @@
  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
  *                          the specified object. Default empty.
- * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
- *                          This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values.
- *               False if there's a problem with the parameters passed to the function.
+ * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
+ *                          This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of values if `$single` is false.
+ *               The value of the meta field if `$single` is true.
+ *               False for an invalid `$object_id` (non-numeric, zero, or negative value),
+ *               or if `$meta_type` is not specified.
+ *               An empty string if a valid but non-existing object ID is passed.
  */
 function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
@@ -522 +525 @@
  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
  *                          the specified object. Default empty.
- * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
- *                          This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values. Null if the value does not exist.
- *               False if there's a problem with the parameters passed to the function.
+ * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
+ *                          This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of values if `$single` is false.
+ *               The value of the meta field if `$single` is true.
+ *               False for an invalid `$object_id` (non-numeric, zero, or negative value),
+ *               or if `$meta_type` is not specified.
+ *               Null if the value does not exist.
  */
 function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = false ) {
@@ -609 +615 @@
  * @param int    $object_id ID of the object metadata is for.
  * @param string $meta_key  Metadata key.
- * @param bool   $single    Optional. If true, return only the first value of the specified meta_key.
- *                          This parameter has no effect if meta_key is not specified. Default false.
- * @return mixed Single metadata value, or array of values.
+ * @param bool   $single    Optional. If true, return only the first value of the specified `$meta_key`.
+ *                          This parameter has no effect if `$meta_key` is not specified. Default false.
+ * @return mixed An array of default values if `$single` is false.
+ *               The default value of the meta field if `$single` is true.
  */
 function get_metadata_default( $meta_type, $object_id, $meta_key, $single = false ) {
@@ -1402 +1409 @@
  * @param int    $object_id ID of the object metadata is for.
  * @param string $meta_key  Metadata key.
- * @param bool   $single    If true, return only the first value of the specified meta_key.
- *                          This parameter has no effect if meta_key is not specified.
+ * @param bool   $single    If true, return only the first value of the specified `$meta_key`.
+ *                          This parameter has no effect if `$meta_key` is not specified.
  * @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.
- * @return mixed Single metadata default, or array of defaults.
+ * @return mixed An array of default values if `$single` is false.
+ *               The default value of the meta field if `$single` is true.
  */
 function filter_default_metadata( $value, $object_id, $meta_key, $single, $meta_type ) {