Ticket #50502: 50502.diff

src/wp-includes/post.php

@@ -2136 +2136 @@
  * @since 1.5.0
  *
  * @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.
+ * @param string $meta_key   Metadata key (this should be raw as opposed to sanitized for database queries).
+ * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar (this should be raw as opposed to sanitized for database queries).
+ * @param mixed  $prev_value Optional. Previous value to check before updating. This is to differentiate between several fields with the same key. If omitted, and there are multiple rows for this post and meta key, all meta values will be updated.
  *                           Default empty.
- * @return int|bool Meta ID if the key didn't exist, true on successful update,
- *                  false on failure.
+ * @return int|bool Meta ID if the key didn't exist; otherwise, true on successful update,
+ *                  false on failure. Note: If the meta_value passed to this function is the same as the value that is already in the database, this function returns false.
  */
 function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
         // Make sure meta is added to the post, not a revision.