Ticket #43069: 43069.diff

wp-includes/meta.php

@@ -993 +993 @@
 }
 
 /**
- * Registers a meta key.
+ * Registers a meta key on all object sub-types of the specified object type.
  *
+ * Once registered the meta key can be used with WordPress's various APIs as
+ * well as the custom post fields box and may leverage consistent input sanitization,
+ * capability control and rest API access.
+ *
  * @since 3.3.0
  * @since 4.6.0 {@link https://core.trac.wordpress.org/ticket/35658 Modified
  *              to support an array of data to attach to registered meta keys}. Previous arguments for
  *              `$sanitize_callback` and `$auth_callback` have been folded into this array.
  *
- * @param string $object_type    Type of object this meta is registered to.
- * @param string $meta_key       Meta key to register.
- * @param array  $args {
+ * @param string       $object_type    Type of object the meta field is being registered to.
+ *                                     Valid values include 'post', 'comment', 'term', 'user' etc.
+ * @param string       $meta_key       Meta key to register.
+ * @param array        $args {
  *     Data used to describe the meta key when registered.
  *
- *     @type string $type              The type of data associated with this meta key.
- *                                     Valid values are 'string', 'boolean', 'integer', and 'number'.
- *     @type string $description       A description of the data attached to this meta key.
- *     @type bool   $single            Whether the meta key has one value per object, or an array of values per object.
- *     @type string $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
- *     @type string $auth_callback     Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.
- *     @type bool   $show_in_rest      Whether data associated with this meta key can be considered public.
+ *     @type string $type              Optional. The type of data associated with this meta key.
+ *                                     Valid values are 'string', 'boolean', 'integer', and 'number'. Default 'string'.
+ *     @type string $description       Optional. A description of the data attached to this meta key. Default empty.
+ *     @type bool   $single            Optional. Whether the meta key has one value per object, or an array of values per object. Default false.
+ *     @type string $sanitize_callback Optional. A function or method to call when sanitizing `$meta_key` data. Default null.
+ *     @type string $auth_callback     Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks. Default null.
+ *     @type bool   $show_in_rest      Optional. Whether data associated with this meta key can be considered public for all objects of the defined object type. Default false.
  * }
- * @param string|array $deprecated Deprecated. Use `$args` instead.
+ * @param string|array $deprecated     Deprecated. Use `$args` instead.
  *
  * @return bool True if the meta key was successfully registered in the global array, false if not.
- *                       Registering a meta key with distinct sanitize and auth callbacks will fire those
- *                       callbacks, but will not add to the global registry.
+ *              Registering a meta key with distinct sanitize and auth callbacks will fire those
+ *              callbacks, but will not add to the global registry.
  */
 function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
         global $wp_meta_keys;
@@ -1035 +1040 @@
                 'show_in_rest'      => false,
         );
 
-        // There used to be individual args for sanitize and auth callbacks
+        // Back-compat: sanitize and auth callbacks were both passed as parameters before the array of arguments was added in 4.6.0.
         $has_old_sanitize_cb = false;
         $has_old_auth_cb     = false;