Docs.

Author: johnbillion

src/wp-includes/comment.php

@@ -446,6 +446,9 @@ function get_comment_count( $post_id = 0 ) {
 /**
  * Adds meta data field to a comment.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @link https://developer.wordpress.org/reference/functions/add_comment_meta/
@@ -470,7 +473,18 @@ function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false
 /**
  * Adds multiple items of meta data to a comment.
  *
- * @todo docs
+ * Examples:
+ *
+ *     bulk_add_comment_meta(
+ *         $comment->comment_ID,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
+ *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
  *
  * @since x.y.z
  *
@@ -489,6 +503,9 @@ function bulk_add_comment_meta( $comment_id, array $meta_fields ) {
  * value, will keep from removing duplicate metadata with the same key. It also
  * allows removing all metadata matching key, if needed.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @link https://developer.wordpress.org/reference/functions/delete_comment_meta/
@@ -555,6 +572,9 @@ function wp_lazyload_comment_meta( array $comment_ids ) {
  *
  * If the meta field for the comment does not exist, it will be added.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @link https://developer.wordpress.org/reference/functions/update_comment_meta/

src/wp-includes/meta.php

@@ -15,6 +15,9 @@
 /**
  * Adds metadata for the specified object.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
@@ -167,19 +170,27 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
 /**
  * Adds multiple items of metadata for the specified object.
  *
- * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes
- * escaped) on input. This means if the data is coming from user-generated
- * content you will need to wp_slash() it before passing it to this function.
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
+ * This function will always insert all of the provided metadata even if matching keys already exist. This behaviour
+ * matches that of add_metadata() when its `$unique` parameter is set to false.
+ *
+ * If the insert fails, no metadata will be inserted. It's not possible for some rows to be inserted and not others.
  *
- * This function will always insert all of the provided metadata even if matching keys
- * already exist. This behaviour matches that of add_metadata() when its `$unique`
- * parameter is set to false.
+ * This is more performant than calling `add_metadata()` multiple times because it only queries the database once and
+ * only clears the meta cache once.
  *
- * If the insert fails, no metadata will be inserted. It's not possible for some rows
- * to be inserted and not others.
+ * Examples:
  *
- * This is more performant than calling `add_metadata()` multiple times because it
- * only queries the database once and only clears the meta cache once.
+ *     bulk_add_metadata(
+ *         'post',
+ *         $post_id,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
  *
  * @todo:
  *
@@ -283,6 +294,9 @@ function bulk_add_metadata( string $meta_type, $object_id, array $meta_fields )
  * Updates metadata for the specified object. If no value already exists for the specified object
  * ID and metadata key, the metadata will be added.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
@@ -478,6 +492,9 @@ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_
 /**
  * Deletes metadata for the specified object.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 2.9.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.

src/wp-includes/ms-site.php

@@ -1022,6 +1022,9 @@ function clean_blog_cache( $blog ) {
 /**
  * Adds metadata to a site.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 5.1.0
  *
  * @param int    $site_id    Site ID.
@@ -1044,7 +1047,18 @@ function add_site_meta( $site_id, $meta_key, $meta_value, $unique = false ) {
 /**
  * Adds multiple items of meta data to a site.
  *
- * @todo docs
+ * Examples:
+ *
+ *     bulk_add_site_meta(
+ *         $site_id,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
+ *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
  *
  * @since x.y.z
  *
@@ -1063,6 +1077,9 @@ function bulk_add_site_meta( $site_id, array $meta_fields ) {
  * value, will keep from removing duplicate metadata with the same key. It also
  * allows removing all metadata matching key, if needed.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 5.1.0
  *
  * @param int    $site_id    Site ID.
@@ -1110,6 +1127,9 @@ function get_site_meta( $site_id, $key = '', $single = false ) {
  *
  * If the meta field for the site does not exist, it will be added.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 5.1.0
  *
  * @param int    $site_id    Site ID.

src/wp-includes/post.php

@@ -2608,6 +2608,9 @@ function get_posts( $args = null ) {
  *
  * Post meta data is called "Custom Fields" on the Administration Screen.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 1.5.0
  *
  * @param int    $post_id    Post ID.
@@ -2636,7 +2639,18 @@ function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
 /**
  * Adds multiple items of meta data to a post.
  *
- * @todo docs
+ * Examples:
+ *
+ *     bulk_add_post_meta(
+ *         $post->ID,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
+ *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
  *
  * @since x.y.z
  *
@@ -2655,6 +2669,9 @@ function bulk_add_post_meta( $post_id, array $meta_fields ) {
  * value, will keep from removing duplicate metadata with the same key. It also
  * allows removing all metadata matching the key, if needed.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 1.5.0
  *
  * @param int    $post_id    Post ID.
@@ -2710,6 +2727,9 @@ function get_post_meta( $post_id, $key = '', $single = false ) {
  *
  * Can be used in place of add_post_meta().
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 1.5.0
  *
  * @param int    $post_id    Post ID.

src/wp-includes/taxonomy.php

@@ -1382,6 +1382,9 @@ function get_terms( $args = array(), $deprecated = '' ) {
 /**
  * Adds metadata to a term.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 4.4.0
  *
  * @param int    $term_id    Term ID.
@@ -1409,7 +1412,18 @@ function add_term_meta( $term_id, $meta_key, $meta_value, $unique = false ) {
 /**
  * Adds multiple items of meta data to a term.
  *
- * @todo docs
+ * Examples:
+ *
+ *     bulk_add_term_meta(
+ *         $term->term_id,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
+ *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
  *
  * @since x.y.z
  *
@@ -1429,6 +1443,9 @@ function bulk_add_term_meta( $term_id, array $meta_fields ) {
 /**
  * Removes metadata matching criteria from a term.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 4.4.0
  *
  * @param int    $term_id    Term ID.
@@ -1475,6 +1492,9 @@ function get_term_meta( $term_id, $key = '', $single = false ) {
  *
  * If the meta field for the term does not exist, it will be added.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 4.4.0
  *
  * @param int    $term_id    Term ID.

src/wp-includes/user.php

@@ -1202,6 +1202,9 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) {
 /**
  * Adds meta data to a user.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 3.0.0
  *
  * @param int    $user_id    User ID.
@@ -1224,7 +1227,18 @@ function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) {
 /**
  * Adds multiple items of meta data to a user.
  *
- * @todo docs
+ * Examples:
+ *
+ *     bulk_add_user_meta(
+ *         $user->ID,
+ *         array(
+ *             'meta_key_1' => 'value_1',
+ *             'meta_key_2' => 'value_2',
+ *         )
+ *     );
+ *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
  *
  * @since x.y.z
  *
@@ -1243,6 +1257,9 @@ function bulk_add_user_meta( $user_id, array $meta_fields ) {
  * value, will keep from removing duplicate metadata with the same key. It also
  * allows removing all metadata matching key, if needed.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 3.0.0
  *
  * @link https://developer.wordpress.org/reference/functions/delete_user_meta/
@@ -1294,6 +1311,9 @@ function get_user_meta( $user_id, $key = '', $single = false ) {
  *
  * If the meta field for the user does not exist, it will be added.
  *
+ * For historial reasons both the meta key and the meta value are expected to be "slashed" (slashes escaped) on input.
+ * This means if data is coming from user-generated content you need to wp_slash() it before passing it to this function.
+ *
  * @since 3.0.0
  *
  * @link https://developer.wordpress.org/reference/functions/update_user_meta/