Index: post.php =================================================================== --- post.php (revision 8662) +++ post.php (working copy) @@ -2,13 +2,9 @@ /** * Post functions and post utility function. * - * Warning: The inline documentation for the functions contained - * in this file might be inaccurate, so the documentation is not - * authoritative at the moment. - * * @package WordPress * @subpackage Post - * @since 1.5 + * @since 1.5.0 */ /** @@ -22,10 +18,8 @@ * prevent looking up the meta name and provide a mechanism for sending the * attached filename through a filter. * - * @package WordPress - * @subpackage Post - * @since 2.0 - * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID + * @since 2.0.0 + * @uses apply_filters() Calls 'get_attached_file' on file path and attachment ID. * * @param int $attachment_id Attachment ID * @param bool $unfiltered Whether to apply filters or not @@ -44,10 +38,8 @@ * Used to update the file path of the attachment, which uses post meta name * '_wp_attached_file' to store the path of the attachment. * - * @package WordPress - * @subpackage Post - * @since 2.1 - * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID + * @since 2.1.0 + * @uses apply_filters() Calls 'update_attached_file' on file path and attachment ID. * * @param int $attachment_id Attachment ID * @param string $file File path for the attachment @@ -79,10 +71,11 @@ * example of what is possible. * * The arguments listed as defaults are for this function and also of the - * get_posts() function. The arguments are combined with the get_children - * defaults and are then passed to the get_posts() function, which accepts - * additional arguments. You can replace the defaults in this function, listed - * below and the additional arguments listed in the get_posts() function. + * {@link get_posts()} function. The arguments are combined with the + * get_children defaults and are then passed to the {@link get_posts()} + * function, which accepts additional arguments. You can replace the defaults in + * this function, listed below and the additional arguments listed in the + * {@link get_posts()} function. * * The 'post_parent' is the most important argument and important attention * needs to be paid to the $args parameter. If you pass either an object or an @@ -103,9 +96,7 @@ * @see get_posts() Has additional arguments that can be replaced. * @internal Claims made in the long description might be inaccurate. * - * @package WordPress - * @subpackage Post - * @since 2.0 + * @since 2.0.0 * * @param mixed $args Optional. User defined arguments for replacing the defaults. * @param string $output Optional. Constant for return type, either OBJECT (default), ARRAY_A, ARRAY_N. @@ -156,16 +147,20 @@ } /** - * get_extended() - Get extended entry info () + * Get extended entry info (). * - * {@internal Missing Long Description}} + * There should not be any space after the second dash and before the word + * 'more'. There can be text or space(s) after the word 'more', but won't be + * referenced. * - * @package WordPress - * @subpackage Post + * The returned array has 'main' and 'extended' keys. Main has the text before + * the . The 'extended' key has the content after the + * comment. + * * @since 1.0.0 * - * @param string $post {@internal Missing Description}} - * @return array {@internal Missing Description}} + * @param string $post Post content. + * @return array Post before ('main') and after ('extended'). */ function get_extended($post) { //Match the new style more links @@ -184,20 +179,19 @@ } /** - * get_post() - Retrieves post data given a post ID or post object. + * Retrieves post data given a post ID or post object. * - * {@internal Missing Long Description}} + * See {@link sanitize_post()} for optional $filter values. Also, the parameter + * $post, must be given as a variable, since it is passed by reference. * - * @package WordPress - * @subpackage Post * @since 1.5.1 * @uses $wpdb * @link http://codex.wordpress.org/Function_Reference/get_post * - * @param int|object &$post post ID or post object - * @param string $output {@internal Missing Description}} - * @param string $filter {@internal Missing Description}} - * @return mixed {@internal Missing Description}} + * @param int|object $post Post ID or post object. + * @param string $output Optional, default is Object. Either OBJECT, ARRAY_A, or ARRAY_N. + * @param string $filter Optional, default is raw. + * @return mixed Post data */ function &get_post(&$post, $output = OBJECT, $filter = 'raw') { global $wpdb; @@ -241,9 +235,7 @@ /** * Retrieve ancestors of a post. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * * @param int|object $post Post ID or post object * @return array Ancestor IDs or empty array if none are found. @@ -266,9 +258,7 @@ * The context values are based off of the taxonomy filter functions and * supported values are found within those functions. * - * @package WordPress - * @subpackage Post - * @since 2.3 + * @since 2.3.0 * @uses sanitize_post_field() See for possible $context values. * * @param string $field Post field name @@ -298,9 +288,7 @@ * This function can be used with any post type, but it makes more sense with * attachments. * - * @package WordPress - * @subpackage Post - * @since 2.0 + * @since 2.0.0 * * @param int $ID Optional. Post ID. * @return bool|string False on failure or returns the mime type @@ -320,9 +308,7 @@ * If the post ID is of an attachment, then the parent post status will be given * instead. * - * @package WordPress - * @subpackage Post - * @since 2.0 + * @since 2.0.0 * * @param int $ID Post ID * @return string|bool Post status or false on failure. @@ -346,9 +332,7 @@ * Posts have a limited set of valid status values, this provides the * post_status values and descriptions. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * * @return array List of post statuses. */ @@ -369,9 +353,7 @@ * Pages have a limited set of valid status values, this provides the * post_status values and descriptions. * - * @package WordPress - * @subpackage Page - * @since 2.5 + * @since 2.5.0 * * @return array List of page statuses. */ @@ -386,19 +368,15 @@ } /** - * get_post_type() - Returns post type + * Retrieve the post type of the current post or of a given post. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * * @uses $wpdb - * @uses $posts {@internal Missing Description}} + * @uses $posts The Loop post global * - * @param mixed $post post object or post ID - * @return mixed post type or false + * @param mixed $post Optional. Post object or post ID. + * @return bool|string post type or false on failure. */ function get_post_type($post = false) { global $posts; @@ -415,20 +393,17 @@ } /** - * set_post_type() - Set post type + * Updates the post type for the post ID. * - * {@internal Missing Long Description}} + * The page or post cache will be cleaned for the post ID. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * * @uses $wpdb - * @uses $posts {@internal Missing Description}} * - * @param mixed $post_id post ID - * @param mixed post type - * @return bool {@internal Missing Description}} + * @param int $post_id Post ID to change post type. Not actually optional. + * @param string $post_type Optional, default is post. Supported values are 'post' or 'page' to name a few. + * @return int Amount of rows changed. Should be 1 for success and 0 for failure. */ function set_post_type( $post_id = 0, $post_type = 'post' ) { global $wpdb; @@ -445,18 +420,16 @@ } /** - * get_posts() - Returns a number of posts + * Retrieve list of latest posts or posts matching criteria. * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post - * @since 1.2 + * @since 1.2.0 * @uses $wpdb * @link http://codex.wordpress.org/Template_Tags/get_posts * - * @param array $args {@internal Missing Description}} - * @return array {@internal Missing Description}} + * @param array $args Optional. Override defaults. + * @return array List of posts. */ function get_posts($args = null) { $defaults = array( @@ -494,21 +467,19 @@ // /** - * add_post_meta() - adds metadata for post + * Add meta data field to a post. * - * {@internal Missing Long Description}} + * Post meta data is called "Custom Fields" on the Administration Panels. * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * @link http://codex.wordpress.org/Function_Reference/add_post_meta * - * @param int $post_id post ID - * @param string $key {@internal Missing Description}} - * @param mixed $value {@internal Missing Description}} - * @param bool $unique whether to check for a value with the same key - * @return bool {@internal Missing Description}} + * @param int $post_id Post ID. + * @param string $key Metadata name. + * @param mixed $value Metadata value. + * @param bool $unique Optional, default is false. Whether the same key should not be added. + * @return bool False for failure. True for success. */ function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) { global $wpdb; @@ -533,20 +504,20 @@ } /** - * delete_post_meta() - delete post metadata + * Remove metadata matching criteria from a post. * - * {@internal Missing Long Description}} + * You can match based on the key, or key and value. Removing based on key and + * value, will keep from removing duplicate metadata with the same key. It also + * allows removing all metadata matching key, if needed. * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * @link http://codex.wordpress.org/Function_Reference/delete_post_meta * * @param int $post_id post ID - * @param string $key {@internal Missing Description}} - * @param mixed $value {@internal Missing Description}} - * @return bool {@internal Missing Description}} + * @param string $key Metadata name. + * @param mixed $value Optional. Metadata value. + * @return bool False for failure. True for success. */ function delete_post_meta($post_id, $key, $value = '') { global $wpdb; @@ -576,20 +547,16 @@ } /** - * get_post_meta() - Get a post meta field + * Retrieve post meta field for a post. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * @link http://codex.wordpress.org/Function_Reference/get_post_meta * - * @param int $post_id post ID - * @param string $key The meta key to retrieve - * @param bool $single Whether to return a single value - * @return mixed {@internal Missing Description}} + * @param int $post_id Post ID. + * @param string $key The meta key to retrieve. + * @param bool $single Whether to return a single value. + * @return mixed Will be an array if $single is false. Will be value of meta data field if $single is true. */ function get_post_meta($post_id, $key, $single = false) { $post_id = (int) $post_id; @@ -620,21 +587,22 @@ } /** - * update_post_meta() - Update a post meta field + * Update post meta field based on post ID. * - * {@internal Missing Long Description}} + * Use the $prev_value parameter to differentiate between meta fields with the + * same key and post ID. * - * @package WordPress - * @subpackage Post + * If the meta field for the post does not exist, it will be added. + * * @since 1.5 * @uses $wpdb * @link http://codex.wordpress.org/Function_Reference/update_post_meta * - * @param int $post_id post ID - * @param string $key {@internal Missing Description}} - * @param mixed $value {@internal Missing Description}} - * @param mixed $prev_value previous value (for differentiating between meta fields with the same key and post ID) - * @return bool {@internal Missing Description}} + * @param int $post_id Post ID. + * @param string $key Metadata key. + * @param mixed $value Metadata value. + * @param mixed $prev_value Optional. Previous value to check before removing. + * @return bool False on failure, true if success. */ function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') { global $wpdb; @@ -662,14 +630,12 @@ } /** - * delete_post_meta_by_key() - Delete everything from post meta matching $post_meta_key + * Delete everything from post meta matching meta key. * - * @package WordPress - * @subpackage Post - * @since 2.3 + * @since 2.3.0 * @uses $wpdb * - * @param string $post_meta_key What to search for when deleting + * @param string $post_meta_key Key to search for when deleting. * @return bool Whether the post meta key was deleted from the database */ function delete_post_meta_by_key($post_meta_key) { @@ -683,17 +649,16 @@ } /** - * get_post_custom() - Retrieve post custom fields + * Retrieve post meta fields, based on post ID. * - * {@internal Missing Long Description}} + * The post meta fields are retrieved from the cache, so the function is + * optimized to be called more than once. It also applies to the functions, that + * use this function. * - * @package WordPress - * @subpackage Post - * @since 1.2 + * @since 1.2.0 * @link http://codex.wordpress.org/Function_Reference/get_post_custom * - * @uses $id - * @uses $wpdb + * @uses $id Current Loop Post ID * * @param int $post_id post ID * @return array {@internal Missing Description}} @@ -713,15 +678,15 @@ } /** - * get_post_custom_keys() - Retrieve post custom field names + * Retrieve meta field names for a post. * - * @package WordPress - * @subpackage Post - * @since 1.2 + * If there are no meta fields, then nothing (null) will be returned. + * + * @since 1.2.0 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys * * @param int $post_id post ID - * @return array|null Either array of the keys, or null if keys would not be retrieved + * @return array|null Either array of the keys, or null if keys could not be retrieved. */ function get_post_custom_keys( $post_id = 0 ) { $custom = get_post_custom( $post_id ); @@ -734,16 +699,17 @@ } /** - * get_post_custom_values() - Retrieve values for a custom post field + * Retrieve values for a custom post field. * - * @package WordPress - * @subpackage Post - * @since 1.2 + * The parameters must not be considered optional. All of the post meta fields + * will be retrieved and only the meta field key values returned. + * + * @since 1.2.0 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values * - * @param string $key field name - * @param int $post_id post ID - * @return mixed {@internal Missing Description}} + * @param string $key Meta field key. + * @param int $post_id Post ID + * @return array Meta field values. */ function get_post_custom_values( $key = '', $post_id = 0 ) { $custom = get_post_custom($post_id); @@ -752,16 +718,15 @@ } /** - * is_sticky() - Check if post is sticky + * Check if post is sticky. * - * {@internal Missing Long Description}} + * Sticky posts should remain at the top of The Loop. If the post ID is not + * given, then The Loop ID for the current post will be used. * - * @package WordPress - * @subpackage Post - * @since 2.7 + * @since 2.7.0 * - * @param int $post_id A post ID - * @return bool + * @param int $post_id Optional. Post ID. + * @return bool Whether post is sticky (true) or not sticky (false). */ function is_sticky($post_id = null) { global $id; @@ -782,18 +747,16 @@ return false; } - /** - * sanitize_post() - Sanitize every post field + * Sanitize every post field. * - * {@internal Missing Long Description}} + * If the context is 'raw', then the post object or array will just be returned. * - * @package WordPress - * @subpackage Post - * @since 2.3 + * @since 2.3.0 + * @uses sanitize_post_field() Used to sanitize the fields. * * @param object|array $post The Post Object or Array - * @param string $context How to sanitize post fields + * @param string $context Optional, default is 'display'. How to sanitize post fields. * @return object|array The now sanitized Post Object or Array (will be the same type as $post) */ function sanitize_post($post, $context = 'display') { @@ -810,19 +773,18 @@ } /** - * sanitize_post_field() - Sanitize post field based on context + * Sanitize post field based on context. * - * {@internal Missing Long Description}} + * Possible context values are: raw, edit, db, attribute, js, and display. The + * display context is used by default. * - * @package WordPress - * @subpackage Post - * @since 2.3 + * @since 2.3.0 * - * @param string $field The Post Object field name - * @param string $value The Post Object value - * @param int $postid Post ID - * @param string $context How to sanitize post fields - * @return string Sanitized value + * @param string $field The Post Object field name. + * @param mixed $value The Post Object value. + * @param int $post_id Post ID. + * @param string $context How to sanitize post fields. + * @return mixed Sanitized value. */ function sanitize_post_field($field, $value, $post_id, $context) { $int_fields = array('ID', 'post_parent', 'menu_order'); @@ -882,15 +844,13 @@ } /** - * Make a post sticky + * Make a post sticky. * - * Makes a post stick to the top of the front page + * Sticky posts should be displayed at the top of the front page. * - * @package WordPress - * @subpackage Post - * @since 2.7 + * @since 2.7.0 * - * @param int $post_id A post ID + * @param int $post_id Post ID. */ function stick_post($post_id) { $stickies = get_option('sticky_posts'); @@ -905,15 +865,13 @@ } /** - * Unstick a post + * Unstick a post. * - * Unstick a post from the front page + * Sticky posts should be displayed at the top of the front page. * - * @package WordPress - * @subpackage Post - * @since 2.7 + * @since 2.7.0 * - * @param int $post_id A post ID + * @param int $post_id Post ID. */ function unstick_post($post_id) { $stickies = get_option('sticky_posts'); @@ -944,9 +902,7 @@ * The $perm parameter checks for 'readable' value and if the user can read * private posts, it will display that for the user that is signed in. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * @link http://codex.wordpress.org/Template_Tags/wp_count_posts * * @param string $type Optional. Post type to retrieve count @@ -988,18 +944,18 @@ /** - * wp_count_attachments() - Count number of attachments + * Count number of attachments for the mime type(s). * - * {@internal Missing Long Description}} + * If you set the optional mime_type parameter, then an array will still be + * returned, but will only have the item you are looking for. It does not give + * you the number of attachments that are children of a post. You can get that + * by counting the number of children that post has. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * - * @param string|array $post_mime_type Array or comma-separated list of MIME patterns - * @return array Number of posts for each post_mime_type + * @param string|array $mime_type Optional. Array or comma-separated list of MIME patterns. + * @return array Number of posts for each mime type. */ - function wp_count_attachments( $mime_type = '' ) { global $wpdb; @@ -1015,13 +971,13 @@ } /** - * wp_match_mime_type() - Check a MIME-Type against a list + * Check a MIME-Type against a list. * - * {@internal Missing Long Description}} + * If the wildcard_mime_types parameter is a string, it must be comma separated + * list. If the real_mime_types is a string, it is also comma separated to + * create the list. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * * @param string|array $wildcard_mime_types e.g. audio/mpeg or image (same as image/*) or flash (same as *flash*) * @param string|array $real_mime_types post_mime_type values @@ -1052,14 +1008,12 @@ } /** - * wp_get_post_mime_type_where() - Convert MIME types into SQL + * Convert MIME types into SQL. * - * @package WordPress - * @subpackage Post - * @since 2.5 + * @since 2.5.0 * - * @param string|array $mime_types MIME types - * @return string SQL AND clause + * @param string|array $mime_types List of mime types or comma separated string of mime types. + * @return string The SQL AND clause for mime searching. */ function wp_post_mime_type_where($post_mime_types) { $where = ''; @@ -1099,16 +1053,13 @@ } /** - * wp_delete_post() - Deletes a Post + * Removes a post, attachment, or page post type. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post * @since 1.0.0 + * @uses do_action() Calls 'deleted_post' hook on post ID. * - * @param int $postid post ID - * @return mixed {@internal Missing Description}} + * @param int $postid Post ID. + * @return mixed */ function wp_delete_post($postid = 0) { global $wpdb, $wp_rewrite; @@ -1177,14 +1128,12 @@ } /** - * wp_get_post_categories() - Retrieve the list of categories for a post + * Retrieve the list of categories for a post. * * Compatibility layer for themes and plugins. Also an easy layer of abstraction * away from the complexity of the taxonomy layer. * - * @package WordPress - * @subpackage Post - * @since 2.1 + * @since 2.1.0 * * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here * @@ -1203,17 +1152,21 @@ } /** - * wp_get_post_tags() - Retrieve the post tags + * Retrieve the tags for a post. * + * There is only one default for this function, called 'fields' and by default + * is set to 'all'. There are other defaults that can be override in + * {@link wp_get_object_terms()}. + * * @package WordPress * @subpackage Post - * @since 2.3 + * @since 2.3.0 * * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here * * @param int $post_id Optional. The Post ID * @param array $args Optional. Overwrite the defaults - * @return mixed The tags the post has currently + * @return array List of post tags. */ function wp_get_post_tags( $post_id = 0, $args = array() ) { $post_id = (int) $post_id; @@ -1227,16 +1180,13 @@ } /** - * wp_get_recent_posts() - Get the $num most recent posts + * Retrieve number of recent posts. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post * @since 1.0.0 + * @uses $wpdb * - * @param int $num number of posts to get - * @return array {@internal Missing Description}} + * @param int $num Optional, default is 10. Number of posts to get. + * @return array List of posts. */ function wp_get_recent_posts($num = 10) { global $wpdb; @@ -1250,21 +1200,19 @@ $sql = "SELECT * FROM $wpdb->posts WHERE post_type = 'post' ORDER BY post_date DESC $limit"; $result = $wpdb->get_results($sql,ARRAY_A); - return $result?$result:array(); + return $result ? $result : array(); } /** - * wp_get_single_post() - Get one post + * Retrieve a single post, based on post ID. * - * {@internal Missing Long Description}} + * Has categories in 'post_category' property or key. Has tags in 'tags_input' + * property or key. * - * @package WordPress - * @subpackage Post * @since 1.0.0 - * @uses $wpdb * - * @param int $postid post ID - * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A + * @param int $postid Post ID + * @param string $mode How to return result, either OBJECT, ARRAY_N, or ARRAY_A. * @return object|array Post object or array holding post contents and information */ function wp_get_single_post($postid = 0, $mode = OBJECT) { @@ -1286,21 +1234,29 @@ } /** - * wp_insert_post() - Insert a post + * wp_insert_post() - * - * {@internal Missing Long Description}} - * * @package WordPress * @subpackage Post - * @since 1.0.0 * + * @uses $allowedtags + * + * @param array $postarr + * @return int post ID or 0 on error + */ +/** + * Insert a post. + * + * {@internal Missing Long Description}} + * + * @since 1.0.0 * @uses $wpdb * @uses $wp_rewrite * @uses $user_ID - * @uses $allowedtags * - * @param array $postarr post contents - * @return int post ID or 0 on error + * @param array $postarr Optional. Override defaults. + * @param bool $wp_error Optional. Allow return of WP_Error on failure. + * @return int|WP_Error {@internal Missing Description}} */ function wp_insert_post($postarr = array(), $wp_error = false) { global $wpdb, $wp_rewrite, $user_ID; @@ -1511,12 +1467,10 @@ * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post * @since 1.0.0 * @uses $wpdb * - * @param array $postarr post data + * @param array|object $postarr post data * @return int {@internal Missing Description}} */ function wp_update_post($postarr = array()) { @@ -1558,14 +1512,11 @@ } /** - * wp_publish_post() - Mark a post as "published" + * Publish a post by transitioning the post status. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 2.1 + * @since 2.1.0 * @uses $wpdb + * @uses do_action() Calls 'edit_post', 'save_post', and 'wp_insert_post' on post_id and post data. * * @param int $post_id Post ID * @return int|null {@internal Missing Description}} @@ -1599,19 +1550,15 @@ } /** - * check_and_publish_future_post() - check to make sure post has correct status before - * passing it on to be published. Invoked by cron 'publish_future_post' event - * This safeguard prevents cron from publishing drafts, etc. + * Publish future post and make sure post ID has future post status. * - * {@internal Missing Long Description}} + * Invoked by cron 'publish_future_post' event. This safeguard prevents cron + * from publishing drafts, etc. * - * @package WordPress - * @subpackage Post - * @since 2.5 - * @uses $wpdb + * @since 2.5.0 * - * @param int $post_id Post ID - * @return int|null {@internal Missing Description}} + * @param int $post_id Post ID. + * @return null Nothing is returned. Which can mean that no action is required or post was published. */ function check_and_publish_future_post($post_id) { @@ -1627,34 +1574,31 @@ } /** - * wp_add_post_tags() - Adds the tags to a post + * Adds tags to a post. * - * @uses wp_set_post_tags() Same first two paraeters, but the last parameter is always set to true. + * @uses wp_set_post_tags() Same first two parameters, but the last parameter is always set to true. * * @package WordPress * @subpackage Post - * @since 2.3 + * @since 2.3.0 * - * @param int $post_id Optional. Post ID - * @param string $tags The tags to set for the post + * @param int $post_id Post ID + * @param string $tags The tags to set for the post, separated by commas. * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise */ function wp_add_post_tags($post_id = 0, $tags = '') { return wp_set_post_tags($post_id, $tags, true); } + /** - * wp_set_post_tags() - Set the tags for a post + * Set the tags for a post. * - * {@internal Missing Long Description}} + * @since 2.3.0 + * @uses wp_set_object_terms() Sets the tags for the post. * - * @package WordPress - * @subpackage Post - * @since 2.3 - * @uses $wpdb - * - * @param int $post_id post ID - * @param string $tags The tags to set for the post + * @param int $post_id Post ID. + * @param string $tags The tags to set for the post, separated by commas. * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise */ @@ -1672,18 +1616,16 @@ } /** - * wp_set_post_categories() - Set categories for a post + * Set categories for a post. * - * {@internal Missing Long Description}} + * If the post categories parameter is not set, then the default category is + * going used. * - * @package WordPress - * @subpackage Post - * @since 2.1 - * @uses $wpdb + * @since 2.1.0 * - * @param int $post_ID post ID - * @param array $post_categories - * @return bool|mixed {@internal Missing Description}} + * @param int $post_ID Post ID. + * @param array $post_categories Optional. List of categories. + * @return bool|mixed */ function wp_set_post_categories($post_ID = 0, $post_categories = array()) { $post_ID = (int) $post_ID; @@ -1697,20 +1639,27 @@ $post_categories = array_unique($post_categories); return wp_set_object_terms($post_ID, $post_categories, 'category'); -} // wp_set_post_categories() +} /** - * wp_transition_post_status() - Change the post transition status + * Transition the post status of a post. * - * {@internal Missing Long Description}} + * Calls hooks to transition post status. If the new post status is not the same + * as the previous post status, then two hooks will be ran, the first is + * 'transition_post_status' with new status, old status, and post data. The + * next action called is 'OLDSTATUS_to_NEWSTATUS' the NEWSTATUS is the + * $new_status parameter and the OLDSTATUS is $old_status parameter; it has the + * post data. * - * @package WordPress - * @subpackage Post - * @since 2.3 + * The final action will run whether or not the post statuses are the same. The + * action is named 'NEWSTATUS_POSTTYPE', NEWSTATUS is from the $new_status + * parameter and POSTTYPE is post_type post data. * - * @param string $new_status {@internal Missing Description}} - * @param string $old_status {@internal Missing Description}} - * @param int $post {@internal Missing Description}} + * @since 2.3.0 + * + * @param string $new_status Transition to this post status. + * @param string $old_status Previous post status. + * @param object $post Post data. */ function wp_transition_post_status($new_status, $old_status, $post) { if ( $new_status != $old_status ) { @@ -1725,18 +1674,14 @@ // /** - * add_ping() - Add a URL to those already pung + * Add a URL to those already pung. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * - * @param int $post_id post ID - * @param string $uri {@internal Missing Description}} - * @return mixed {@internal Missing Description}} + * @param int $post_id Post ID. + * @param string $uri Ping URI. + * @return int How many rows were updated. */ function add_ping($post_id, $uri) { global $wpdb; @@ -1752,17 +1697,13 @@ } /** - * get_enclosed() - Get enclosures already enclosed for a post + * Retrieve enclosures already enclosed for a post. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * - * @param int $post_id post ID - * @return array {@internal Missing Description}} + * @param int $post_id Post ID. + * @return array List of enclosures */ function get_enclosed($post_id) { $custom_fields = get_post_custom( $post_id ); @@ -1783,17 +1724,13 @@ } /** - * get_pung() - Get URLs already pinged for a post + * Retrieve URLs already pinged for a post. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * - * @param int $post_id post ID - * @return array {@internal Missing Description}} + * @param int $post_id Post ID. + * @return array */ function get_pung($post_id) { global $wpdb; @@ -1805,17 +1742,13 @@ } /** - * get_to_ping() - Get any URLs in the todo list + * Retrieve URLs that need to be pinged. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * - * @param int $post_id post ID - * @return array {@internal Missing Description}} + * @param int $post_id Post ID + * @return array */ function get_to_ping($post_id) { global $wpdb; @@ -1827,19 +1760,15 @@ } /** - * trackback_url_list() - Do trackbacks for a list of urls + * Do trackbacks for a list of URLs. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post * @since 1.0.0 * - * @param string $tb_list comma separated list of URLs - * @param int $post_id post ID + * @param string $tb_list Comma separated list of URLs + * @param int $post_id Post ID */ function trackback_url_list($tb_list, $post_id) { - if (!empty($tb_list)) { + if ( ! empty( $tb_list ) ) { // get post data $postdata = wp_get_single_post($post_id, ARRAY_A); @@ -1847,7 +1776,7 @@ extract($postdata, EXTR_SKIP); // form an excerpt - $excerpt = strip_tags($post_excerpt?$post_excerpt:$post_content); + $excerpt = strip_tags($post_excerpt ? $post_excerpt : $post_content); if (strlen($excerpt) > 255) { $excerpt = substr($excerpt,0,252) . '...'; @@ -1855,10 +1784,10 @@ $trackback_urls = explode(',', $tb_list); foreach( (array) $trackback_urls as $tb_url) { - $tb_url = trim($tb_url); - trackback($tb_url, stripslashes($post_title), $excerpt, $post_id); + $tb_url = trim($tb_url); + trackback($tb_url, stripslashes($post_title), $excerpt, $post_id); } - } + } } // @@ -1866,16 +1795,12 @@ // /** - * get_all_page_ids() - Get a list of page IDs + * Get a list of page IDs. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 2.0 + * @since 2.0.0 * @uses $wpdb * - * @return array {@internal Missing Description}} + * @return array List of page IDs. */ function get_all_page_ids() { global $wpdb; @@ -1889,18 +1814,14 @@ } /** - * get_page() - Retrieves page data given a page ID or page object + * Retrieves page data given a page ID or page object. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post * @since 1.5.1 * - * @param mixed &$page page object or page ID - * @param string $output what to output + * @param mixed $page Page object or page ID. Passed by reference. + * @param string $output What to output. OBJECT, ARRAY_A, or ARRAY_N. * @param string $filter How the return value should be filtered. - * @return mixed {@internal Missing Description}} + * @return mixed Page data. */ function &get_page(&$page, $output = OBJECT, $filter = 'raw') { if ( empty($page) ) { @@ -1916,18 +1837,14 @@ } /** - * get_page_by_path() - Retrieves a page given its path + * Retrieves a page given its path. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 2.1 + * @since 2.1.0 * @uses $wpdb * - * @param string $page_path page path - * @param string $output output type - * @return mixed {@internal Missing Description}} + * @param string $page_path Page path + * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. + * @return mixed Null when complete. */ function get_page_by_path($page_path, $output = OBJECT) { global $wpdb; @@ -1944,7 +1861,7 @@ $pages = $wpdb->get_results( $wpdb->prepare( "SELECT ID, post_name, post_parent FROM $wpdb->posts WHERE post_name = %s AND (post_type = 'page' OR post_type = 'attachment')", $leaf_path )); if ( empty($pages) ) - return NULL; + return null; foreach ($pages as $page) { $path = '/' . $leaf_path; @@ -1958,22 +1875,18 @@ return get_page($page->ID, $output); } - return NULL; + return null; } /** - * get_page_by_title() - Retrieve a page given its title + * Retrieve a page given its title. * - * {@internal Missing Long Description}} - * - * @package WordPress - * @subpackage Post - * @since 2.1 + * @since 2.1.0 * @uses $wpdb * - * @param string $page_title page title - * @param string $output output type - * @return mixed {@internal Missing Description}} + * @param string $page_title Page title + * @param string $output Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A. + * @return mixed */ function get_page_by_title($page_title, $output = OBJECT) { global $wpdb; @@ -1981,7 +1894,7 @@ if ( $page ) return get_page($page, $output); - return NULL; + return null; } /** @@ -1989,8 +1902,6 @@ * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post * @since 1.5.1 * * @param int $page_id page ID @@ -2036,16 +1947,12 @@ } /** - * get_page_uri() - Builds a page URI + * Builds a page URI. * - * {@internal Missing Long Description}} + * @since 1.5.0 * - * @package WordPress - * @subpackage Post - * @since 1.5 - * - * @param int $page_id page ID - * @return string {@internal Missing Description}} + * @param int $page_id Page ID. + * @return string Page URI. */ function get_page_uri($page_id) { $page = get_page($page_id); @@ -2064,16 +1971,14 @@ } /** - * get_pages() - Retrieve a list of pages + * Retrieve a list of pages. * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post - * @since 1.5 + * @since 1.5.0 * @uses $wpdb * - * @param mixed $args Optional. Array or string of options + * @param mixed $args Optional. Array or string of options that overrides defaults. * @return array List of pages matching defaults or $args */ function &get_pages($args = '') { @@ -2198,16 +2103,12 @@ // /** - * is_local_attachment() - Check if the attachment URI is local one and is really an attachment. + * Check if the attachment URI is local one and is really an attachment. * - * {@internal Missing Long Description}} + * @since 2.0.0 * - * @package WordPress - * @subpackage Post - * @since 2.0 - * * @param string $url URL to check - * @return bool {@internal Missing Description}} + * @return bool True on success, false on failure. */ function is_local_attachment($url) { if (strpos($url, get_bloginfo('url')) === false) @@ -2223,20 +2124,17 @@ } /** - * wp_insert_attachment() - Insert an attachment + * Insert an attachment. * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post - * @since 2.0 - * + * @since 2.0.0 * @uses $wpdb * @uses $user_ID * - * @param object $object attachment object - * @param string $file filename - * @param int $post_parent parent post ID + * @param object $object Attachment object. + * @param string $file Optional filename. + * @param int $post_parent Parent post ID. * @return int {@internal Missing Description}} */ function wp_insert_attachment($object, $file = false, $parent = 0) { @@ -2367,17 +2265,15 @@ } /** - * wp_delete_attachment() - Delete an attachment + * Delete an attachment. * - * {@internal Missing Long Description}} + * Will remove the file also, when the attachment is removed. * - * @package WordPress - * @subpackage Post - * @since 2.0 + * @since 2.0.0 * @uses $wpdb * - * @param int $postid attachment Id - * @return mixed {@internal Missing Description}} + * @param int $postid Attachment ID + * @return mixed False on failure. Post data on success. */ function wp_delete_attachment($postid) { global $wpdb; @@ -2431,17 +2327,13 @@ } /** - * wp_get_attachment_metadata() - Retrieve metadata for an attachment + * Retrieve attachment meta field for attachment ID. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * - * @param int $post_id attachment ID - * @param bool $unfiltered Optional, default is false. If true, filters are not run - * @return array {@internal Missing Description}} + * @param int $post_id Attachment ID + * @param bool $unfiltered Optional, default is false. If true, filters are not run. + * @return string|bool Attachment meta field. False on failure. */ function wp_get_attachment_metadata( $post_id, $unfiltered = false ) { $post_id = (int) $post_id; @@ -2455,17 +2347,13 @@ } /** - * wp_update_attachment_metadata() - Update metadata for an attachment + * Update metadata for an attachment. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * * @param int $post_id attachment ID * @param array $data attachment data - * @return int {@internal Missing Description}} + * @return int */ function wp_update_attachment_metadata( $post_id, $data ) { $post_id = (int) $post_id; @@ -2478,16 +2366,12 @@ } /** - * wp_get_attachment_url() - Retrieve the URL for an attachment + * Retrieve the URL for an attachment. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * - * @param int $post_id attachment ID - * @return string {@internal Missing Description}} + * @param int $post_id Attachment ID. + * @return string */ function wp_get_attachment_url( $post_id = 0 ) { $post_id = (int) $post_id; @@ -2503,16 +2387,12 @@ } /** - * wp_get_attachment_thumb_file() - Retrieve thumbnail for an attachment + * Retrieve thumbnail for an attachment. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * - * @param int $post_id attachment ID - * @return mixed {@internal Missing Description}} + * @param int $post_id Attachment ID. + * @return mixed False on failure. Thumbnail file path on success. */ function wp_get_attachment_thumb_file( $post_id = 0 ) { $post_id = (int) $post_id; @@ -2529,16 +2409,12 @@ } /** - * wp_get_attachment_thumb_url() - Retrieve URL for an attachment thumbnail + * Retrieve URL for an attachment thumbnail. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * - * @param int $post_id attachment ID - * @return string {@internal Missing Description}} + * @param int $post_id Attachment ID + * @return string|bool False on failure. Thumbnail URL on success. */ function wp_get_attachment_thumb_url( $post_id = 0 ) { $post_id = (int) $post_id; @@ -2560,16 +2436,12 @@ } /** - * wp_attachment_is_image() - Check if the attachment is an image + * Check if the attachment is an image. * - * {@internal Missing Long Description}} + * @since 2.1.0 * - * @package WordPress - * @subpackage Post - * @since 2.1 - * - * @param int $post_id attachment ID - * @return bool {@internal Missing Description}} + * @param int $post_id Attachment ID + * @return bool */ function wp_attachment_is_image( $post_id = 0 ) { $post_id = (int) $post_id; @@ -2589,13 +2461,11 @@ } /** - * wp_mime_type_icon() - Retrieve the icon for a MIME type + * Retrieve the icon for a MIME type. * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post - * @since 2.1 + * @since 2.1.0 * * @param string $mime MIME type * @return string|bool {@internal Missing Description}} @@ -2679,15 +2549,13 @@ } /** - * wp_check_for_changed_slugs() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * * {@internal Missing Long Description}} * - * @package WordPress - * @subpackage Post * @since 2.1 * - * @param int $post_id The Post ID + * @param int $post_id Post ID. * @return int Same as $post_id */ function wp_check_for_changed_slugs($post_id) { @@ -2718,17 +2586,14 @@ } /** - * get_private_posts_cap_sql() - {@internal Missing Short Description}} + * {@internal Missing Short Description}} * - * This function provides a standardized way to appropriately select on - * the post_status of posts/pages. The function will return a piece of - * SQL code that can be added to a WHERE clause; this SQL is constructed - * to allow all published posts, and all private posts to which the user - * has access. + * This function provides a standardized way to appropriately select on the + * post_status of posts/pages. The function will return a piece of SQL code that + * can be added to a WHERE clause; this SQL is constructed to allow all + * published posts, and all private posts to which the user has access. * - * @package WordPress - * @subpackage Post - * @since 2.2 + * @since 2.2.0 * * @uses $user_ID * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types @@ -2859,9 +2724,9 @@ } /** - * update_post_cache() - Updates posts in cache + * Updates posts in cache. * - * @usedby update_page_cache() update_page_cache() aliased by this function. + * @usedby update_page_cache() Aliased by this function. * * @package WordPress * @subpackage Cache @@ -2878,14 +2743,14 @@ } /** - * clean_post_cache() - Will clean the post in the cache + * Will clean the post in the cache. * - * Cleaning means delete from the cache of the post. Will call to clean - * the term object cache associated with the post ID. + * Cleaning means delete from the cache of the post. Will call to clean the term + * object cache associated with the post ID. * * @package WordPress * @subpackage Cache - * @since 2.0 + * @since 2.0.0 * * @uses do_action() Will call the 'clean_post_cache' hook action. * @@ -2911,7 +2776,7 @@ } /** - * update_page_cache() - Alias of update_post_cache() + * Alias of update_post_cache(). * * @see update_post_cache() Posts and pages are the same, alias is intentional * @@ -2926,10 +2791,10 @@ } /** - * clean_page_cache() - Will clean the page in the cache + * Will clean the page in the cache. * - * Clean (read: delete) page from cache that matches $id. Will also clean - * cache associated with 'all_page_ids' and 'get_pages'. + * Clean (read: delete) page from cache that matches $id. Will also clean cache + * associated with 'all_page_ids' and 'get_pages'. * * @package WordPress * @subpackage Cache @@ -2949,11 +2814,11 @@ } /** - * update_post_caches() - Call major cache updating functions for list of Post objects. + * Call major cache updating functions for list of Post objects. * * @package WordPress * @subpackage Cache - * @since 1.5 + * @since 1.5.0 * * @uses $wpdb * @uses update_post_cache() @@ -3080,13 +2945,13 @@ } /** - * _future_post_hook() - Hook used to schedule publication for a post marked for the future. + * Hook used to schedule publication for a post marked for the future. * * The $post properties used and must exist are 'ID' and 'post_date_gmt'. * * @package WordPress * @subpackage Post - * @since 2.3 + * @since 2.3.0 * * @param int $post_id Not Used. Can be set to null. * @param object $post Object type containing the post information @@ -3132,7 +2997,7 @@ } /** - * _save_post_hook() - Hook used to prevent page/post cache and rewrite rules from staying dirty + * Hook used to prevent page/post cache and rewrite rules from staying dirty. * * Does two things. If the post is a page and has a template then it will update/add that * template to the meta. For both pages and posts, it will clean the post cache to make sure @@ -3143,7 +3008,7 @@ * * @package WordPress * @subpackage Post - * @since 2.3 + * @since 2.3.0 * * @uses $wp_rewrite Flushes Rewrite Rules. * @@ -3164,6 +3029,11 @@ // Private // +/** + * + * + * @param unknown_type $_post + */ function _get_post_ancestors(&$_post) { global $wpdb; @@ -3183,22 +3053,21 @@ } } -/* Post Revisions */ - /** - * _wp_post_revision_fields() - determines which fields of posts are to be saved in revisions + * Determines which fields of posts are to be saved in revisions. * - * Does two things. If passed a post *array*, it will return a post array ready to be - * insterted into the posts table as a post revision. - * Otherwise, returns an array whose keys are the post fields to be saved for post revisions. + * Does two things. If passed a post *array*, it will return a post array ready + * to be insterted into the posts table as a post revision. Otherwise, returns + * an array whose keys are the post fields to be saved for post revisions. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 + * @access private * - * @param array $post optional a post array to be processed for insertion as a post revision + * @param array $post Optional a post array to be processed for insertion as a post revision. * @param bool $autosave optional Is the revision an autosave? - * @return array post array ready to be inserted as a post revision or array of fields that can be versioned + * @return array Post array ready to be inserted as a post revision or array of fields that can be versioned. */ function _wp_post_revision_fields( $post = null, $autosave = false ) { static $fields = false; @@ -3237,16 +3106,18 @@ } /** - * wp_save_post_revision() - Saves an already existing post as a post revision. Typically used immediately prior to post updates. + * Saves an already existing post as a post revision. * + * Typically used immediately prior to post updates. + * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses _wp_put_post_revision() * - * @param int $post_id The ID of the post to save as a revision - * @return mixed null or 0 if error, new revision ID if success + * @param int $post_id The ID of the post to save as a revision. + * @return mixed Null or 0 if error, new revision ID, if success. */ function wp_save_post_revision( $post_id ) { // We do autosaves manually with wp_create_post_autosave() @@ -3290,16 +3161,17 @@ } /** - * wp_get_post_autosave() - returns the autosaved data of the specified post. + * Retrieve the autosaved data of the specified post. * - * Returns a post object containing the information that was autosaved for the specified post. + * Returns a post object containing the information that was autosaved for the + * specified post. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * - * @param int $post_id The post ID - * @return object|bool the autosaved data or false on failure or when no autosave exists + * @param int $post_id The post ID. + * @return object|bool The autosaved data or false on failure or when no autosave exists. */ function wp_get_post_autosave( $post_id ) { global $wpdb; @@ -3326,21 +3198,28 @@ return false; } -// Internally used to hack WP_Query into submission +/** + * Internally used to hack WP_Query into submission. + * + * @package WordPress + * @subpackage Post_Revisions + * @since 2.6.0 + * + * @param object $query WP_Query object + */ function _wp_get_post_autosave_hack( $query ) { $query->is_single = false; } - /** - * wp_is_post_revision() - Determines if the specified post is a revision. + * Determines if the specified post is a revision. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * - * @param int|object $post post ID or post object - * @return bool|int false if not a revision, ID of revision's parent otherwise + * @param int|object $post Post ID or post object. + * @return bool|int False if not a revision, ID of revision's parent otherwise. */ function wp_is_post_revision( $post ) { if ( !$post = wp_get_post_revision( $post ) ) @@ -3349,14 +3228,14 @@ } /** - * wp_is_post_autosave() - Determines if the specified post is an autosave. + * Determines if the specified post is an autosave. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * - * @param int|object $post post ID or post object - * @return bool|int false if not a revision, ID of autosave's parent otherwise + * @param int|object $post Post ID or post object. + * @return bool|int False if not a revision, ID of autosave's parent otherwise */ function wp_is_post_autosave( $post ) { if ( !$post = wp_get_post_revision( $post ) ) @@ -3367,17 +3246,17 @@ } /** - * _wp_put_post_revision() - Inserts post data into the posts table as a post revision + * Inserts post data into the posts table as a post revision. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses wp_insert_post() * - * @param int|object|array $post post ID, post object OR post array - * @param bool $autosave optional Is the revision an autosave? - * @return mixed null or 0 if error, new revision ID if success + * @param int|object|array $post Post ID, post object OR post array. + * @param bool $autosave Optional. Is the revision an autosave? + * @return mixed Null or 0 if error, new revision ID if success. */ function _wp_put_post_revision( $post = null, $autosave = false ) { if ( is_object($post) ) @@ -3402,18 +3281,18 @@ } /** - * wp_get_post_revision() - Gets a post revision + * Gets a post revision. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses get_post() * - * @param int|object $post post ID or post object - * @param $output optional OBJECT, ARRAY_A, or ARRAY_N - * @param string $filter optional sanitation filter. @see sanitize_post() - * @return mixed null if error or post object if success + * @param int|object $post Post ID or post object + * @param string $output Optional. OBJECT, ARRAY_A, or ARRAY_N. + * @param string $filter Optional sanitation filter. @see sanitize_post() + * @return mixed Null if error or post object if success */ function &wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') { $null = null; @@ -3436,20 +3315,21 @@ } /** - * wp_restore_post_revision() - Restores a post to the specified revision + * Restores a post to the specified revision. * - * Can restore a past using all fields of the post revision, or only selected fields. + * Can restore a past using all fields of the post revision, or only selected + * fields. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses wp_get_post_revision() * @uses wp_update_post() * - * @param int|object $revision_id revision ID or revision object - * @param array $fields optional What fields to restore from. Defaults to all. - * @return mixed null if error, false if no fields to restore, (int) post ID if success + * @param int|object $revision_id Revision ID or revision object. + * @param array $fields Optional. What fields to restore from. Defaults to all. + * @return mixed Null if error, false if no fields to restore, (int) post ID if success. */ function wp_restore_post_revision( $revision_id, $fields = null ) { if ( !$revision = wp_get_post_revision( $revision_id, ARRAY_A ) ) @@ -3478,20 +3358,20 @@ } /** - * wp_delete_post_revision() - Deletes a revision. + * Deletes a revision. * - * Deletes the row from the posts table corresponding to the specified revision + * Deletes the row from the posts table corresponding to the specified revision. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses wp_get_post_revision() * @uses wp_delete_post() * - * @param int|object $revision_id revision ID or revision object - * @param array $fields optional What fields to restore from. Defaults to all. - * @return mixed null if error, false if no fields to restore, (int) post ID if success + * @param int|object $revision_id Revision ID or revision object. + * @param array $fields Optional. What fields to restore from. Defaults to all. + * @return mixed Null if error, false if no fields to restore, (int) post ID if success. */ function wp_delete_post_revision( $revision_id ) { if ( !$revision = wp_get_post_revision( $revision_id ) ) @@ -3508,15 +3388,15 @@ } /** - * wp_get_post_revisions() - Returns all revisions of specified post + * Returns all revisions of specified post. * * @package WordPress - * @subpackage Post Revisions - * @since 2.6 + * @subpackage Post_Revisions + * @since 2.6.0 * * @uses get_children() * - * @param int|object $post_id post ID or post object + * @param int|object $post_id Post ID or post object * @return array empty if no revisions */ function wp_get_post_revisions( $post_id = 0, $args = null ) {