Changeset 12761

Timestamp:

01/19/2010 05:08:04 PM (15 years ago)

Author:

ryan

Message:

phpdoc for metadata API. Props wnorris. fixes #11943

File:

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

trunk/wp-includes/meta.php

@@ -1 +1 @@
 <?php
 /**
- * Meta API
- *
- * Functions for retrieving and manipulating metadata
+ * Metadata API
+ *
+ * Functions for retrieving and manipulating metadata of various WordPress object types.  Metadata 
+ * for an object is a represented by a simple key-value pair.  Objects may contain multiple 
+ * metadata entries that share the same key and differ only in their value.
  *
  * @package WordPress
@@ -10 +12 @@
  */
 
+/**
+ * Add metadata for the specified object.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'added_{$meta_type}_meta' with meta_id of added metadata entry,
+ *      object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Metadata value
+ * @param bool $unique Optional, default is false.  Whether the specified metadata key should be 
+ *      unique for the object.  If true, and the object already has a value for the specified 
+ *      metadata key, no change will be made
+ * @return bool True on successful update, false on failure.
+ */
 function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
     if ( !$meta_type || !$meta_key )
@@ -44 +63 @@
 }
 
+/**
+ * Update metadata for the specified object.  If no value already exists for the specified object 
+ * ID and metadata key, the metadata will be added.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'update_{$meta_type}_meta' before updating metadata with meta_id of 
+ *      metadata entry to update, object ID, meta key, and meta value
+ * @uses do_action() Calls 'updated_{$meta_type}_meta' after updating metadata with meta_id of 
+ *      updated metadata entry, object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Metadata value
+ * @param string $prev_value Optional.  If specified, only update existing metadata entries with 
+ *      the specified value.  Otherwise, update all entries.
+ * @return bool True on successful update, false on failure.
+ */
 function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
     if ( !$meta_type || !$meta_key )
@@ -82 +120 @@
 }
 
+/**
+ * Delete metadata for the specified object.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'deleted_{$meta_type}_meta' after deleting with meta_id of 
+ *      deleted metadata entries, object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Optional. Metadata value.  If specified, only delete metadata entries 
+ *      with this value.  Otherwise, delete all entries with the specified meta_key.
+ * @param bool $delete_all Optional, default is false.  If true, delete matching metadata entries 
+ *      for all objects, ignoring the specified object_id.  Otherwise, only delete matching 
+ *      metadata entries for the specified object_id.
+ * @return bool True on successful delete, false on failure.
+ */
 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
     if ( !$meta_type || !$meta_key || (!$delete_all && ! (int)$object_id) )
@@ -123 +179 @@
 }
 
+/**
+ * Retrieve metadata for the specified object.
+ *
+ * @since 2.9.0
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Optional.  Metadata key.  If not specified, retrieve all metadata for 
+ *      the specified object.
+ * @param bool $single Optional, default is false.  If true, return only the first value of the 
+ *      specified meta_key.  This parameter has no effect if meta_key is not specified.
+ * @return string|array Single metadata value, or array of values
+ */
 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
     if ( !$meta_type )
@@ -151 +220 @@
 }
 
+/**
+ * Update the metadata cache for the specified objects.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
+ * @return mixed Metadata cache for the specified objects, or false on failure.
+ */
 function update_meta_cache($meta_type, $object_ids) {
     if ( empty( $meta_type ) || empty( $object_ids ) )
@@ -213 +292 @@
 }
 
+/**
+ * Retrieve the name of the metadata table for the specified object type.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ *
+ * @param string $meta_type Type of object to get metadata table for (e.g., comment, post, or user)
+ * @return mixed Metadata table name, or false if no metadata table exists
+ */
 function _get_meta_table($type) {
     global $wpdb;