From 42b36e1e64ea49f2131859a3e345b083c03a4a95 Mon Sep 17 00:00:00 2001
From: ryan <ryan@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Tue, 19 Aug 2008 16:38:06 +0000
Subject: [PATCH] post.php phpdoc. Props santosj. fixes #7538

git-svn-id: http://svn.automattic.com/wordpress/trunk@8669 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/post.php | 1214 ++++++++++++++++++++----------------------
 1 file changed, 583 insertions(+), 631 deletions(-)

diff --git a/wp-includes/post.php b/wp-includes/post.php
index 46b0f6cfd8..236255caad 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -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 @@ function get_attached_file( $attachment_id, $unfiltered = false ) {
  * 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 @@ function update_attached_file( $attachment_id, $file ) {
  * 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 @@ function update_attached_file( $attachment_id, $file ) {
  * @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 @@ function &get_children($args = '', $output = OBJECT) {
 }
 
 /**
- * get_extended() - Get extended entry info (<!--more-->)
+ * Get extended entry info (<!--more-->).
  *
- * {@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.
+ *
+ * The returned array has 'main' and 'extended' keys. Main has the text before
+ * the <code><!--more--></code>. The 'extended' key has the content after the
+ * <code><!--more--></code> comment.
  *
- * @package WordPress
- * @subpackage Post
  * @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 @@ function get_extended($post) {
 }
 
 /**
- * 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 @@ function &get_post(&$post, $output = OBJECT, $filter = 'raw') {
 /**
  * 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 @@ function get_post_ancestors($post) {
  * 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 @@ function get_post_field( $field, $post, $context = 'display' ) {
  * 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 @@ function get_post_mime_type($ID = '') {
  * 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 @@ function get_post_status($ID = '') {
  * 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 @@ function get_post_statuses( ) {
  * 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 @@ function get_page_statuses( ) {
 }
 
 /**
- * get_post_type() - Returns post type
+ * Retrieve the post type of the current post or of a given post.
  *
- * {@internal Missing Long Description}}
- *
- * @package WordPress
- * @subpackage Post
- * @since 2.1
+ * @since 2.1.0
  *
  * @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 @@ function get_post_type($post = false) {
 }
 
 /**
- * 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,29 @@ function set_post_type( $post_id = 0, $post_type = 'post' ) {
 }
 
 /**
- * get_posts() - Returns a number of posts
+ * Retrieve list of latest posts or posts matching criteria.
  *
- * {@internal Missing Long Description}}
+ * The defaults are as follows:
+ *     'numberposts' - Default is 5. Total number of posts to retrieve.
+ *     'offset' - Default is 0. See {@link WP_Query::query()} for more.
+ *     'category' - What category to pull the posts from.
+ *     'orderby' - Default is 'post_date'. How to order the posts.
+ *     'order' - Default is 'DESC'. The order to retrieve the posts.
+ *     'include' - See {@link WP_Query::query()} for more.
+ *     'exclude' - See {@link WP_Query::query()} for more.
+ *     'meta_key' - See {@link WP_Query::query()} for more.
+ *     'meta_value' - See {@link WP_Query::query()} for more.
+ *     'post_type' - Default is 'post'. Can be 'page', or 'attachment' to name a few.
+ *     'post_parent' - The parent of the post or post type.
+ *     'post_status' - Default is 'published'. Post status to retrieve.
  *
- * @package WordPress
- * @subpackage Post
- * @since 1.2
+ * @since 1.2.0
  * @uses $wpdb
+ * @uses WP_Query::query() See for more default arguments and information.
  * @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 +480,19 @@ function get_posts($args = null) {
 //
 
 /**
- * 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 +517,20 @@ function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) {
 }
 
 /**
- * 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 +560,16 @@ function delete_post_meta($post_id, $key, $value = '') {
 }
 
 /**
- * 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 +600,22 @@ function get_post_meta($post_id, $key, $single = false) {
 }
 
 /**
- * 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.
+ *
+ * If the meta field for the post does not exist, it will be added.
  *
- * @package WordPress
- * @subpackage Post
  * @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 +643,12 @@ function update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '') {
 }
 
 /**
- * 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,20 +662,19 @@ function delete_post_meta_by_key($post_meta_key) {
 }
 
 /**
- * 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}}
+ * @return array
  */
 function get_post_custom($post_id = 0) {
 	global $id;
@@ -713,15 +691,15 @@ function get_post_custom($post_id = 0) {
 }
 
 /**
- * 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 +712,17 @@ function get_post_custom_keys( $post_id = 0 ) {
 }
 
 /**
- * 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 +731,15 @@ function get_post_custom_values( $key = '', $post_id = 0 ) {
 }
 
 /**
- * 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 +760,16 @@ function is_sticky($post_id = null) {
 	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 +786,18 @@ function sanitize_post($post, $context = 'display') {
 }
 
 /**
- * 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 +857,13 @@ function sanitize_post_field($field, $value, $post_id, $context) {
 }
 
 /**
- * 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 +878,13 @@ function stick_post($post_id) {
 }
 
 /**
- * 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 +915,7 @@ function unstick_post($post_id) {
  * 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 +957,18 @@ function wp_count_posts( $type = 'post', $perm = '' ) {
 
 
 /**
- * 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 +984,13 @@ function wp_count_attachments( $mime_type = '' ) {
 }
 
 /**
- * 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 +1021,12 @@ function wp_match_mime_types($wildcard_mime_types, $real_mime_types) {
 }
 
 /**
- * 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 +1066,16 @@ function wp_post_mime_type_where($post_mime_types) {
 }
 
 /**
- * wp_delete_post() - Deletes a Post
+ * Removes a post, attachment, or page.
  *
- * {@internal Missing Long Description}}
+ * When the post and page goes, everything that is tied to it is deleted also.
+ * This includes comments, post meta fields, and terms associated with the post.
  *
- * @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,20 +1144,18 @@ function wp_delete_post($postid = 0) {
 }
 
 /**
- * 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
+ * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here.
  *
- * @param int $post_id Optional. The Post ID
- * @param array $args Optional. Overwrite the defaults
- * @return array {@internal Missing Description}}
+ * @param int $post_id Optional. The Post ID.
+ * @param array $args Optional. Overwrite the defaults.
+ * @return array
  */
 function wp_get_post_categories( $post_id = 0, $args = array() ) {
 	$post_id = (int) $post_id;
@@ -1203,17 +1168,21 @@ function wp_get_post_categories( $post_id = 0, $args = array() ) {
 }
 
 /**
- * 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 +1196,13 @@ function wp_get_post_tags( $post_id = 0, $args = array() ) {
 }
 
 /**
- * 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 +1216,19 @@ function wp_get_recent_posts($num = 10) {
 	$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 +1250,40 @@ function wp_get_single_post($postid = 0, $mode = OBJECT) {
 }
 
 /**
- * wp_insert_post() - Insert a post
+ * Insert a post.
  *
- * {@internal Missing Long Description}}
+ * If the $postarr parameter has 'ID' set to a value, then post will be updated.
+ *
+ * You can set the post date manually, but setting the values for 'post_date'
+ * and 'post_date_gmt' keys. You can close the comments or open the comments by
+ * setting the value for 'comment_status' key.
+ *
+ * The defaults for the parameter $postarr are:
+ *     'post_status' - Default is 'draft'.
+ *     'post_type' - Default is 'post'.
+ *     'post_author' - Default is current user ID. The ID of the user, who added
+ *         the post.
+ *     'ping_status' - Default is the value in default ping status option.
+ *         Whether the attachment can accept pings.
+ *     'post_parent' - Default is 0. Set this for the post it belongs to, if
+ *         any.
+ *     'menu_order' - Default is 0. The order it is displayed.
+ *     'to_ping' - Whether to ping.
+ *     'pinged' - Default is empty string.
+ *     'post_password' - Default is empty string. The password to access the
+ *         attachment.
+ *     'guid' - Global Unique ID for referencing the attachment.
+ *     'post_content_filtered' - Post content filtered.
+ *     'post_excerpt' - Post excerpt.
  *
- * @package WordPress
- * @subpackage Post
  * @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 The value 0 or WP_Error on failure. The post ID on success.
  */
 function wp_insert_post($postarr = array(), $wp_error = false) {
 	global $wpdb, $wp_rewrite, $user_ID;
@@ -1507,17 +1490,15 @@ function wp_insert_post($postarr = array(), $wp_error = false) {
 }
 
 /**
- * wp_update_post() - Update a post
+ * Update a post with new post data.
  *
- * {@internal Missing Long Description}}
+ * The date does not have to be set for drafts. You can set the date and it will
+ * not be overridden.
  *
- * @package WordPress
- * @subpackage Post
  * @since 1.0.0
- * @uses $wpdb
  *
- * @param array $postarr post data
- * @return int {@internal Missing Description}}
+ * @param array|object $postarr Post data.
+ * @return int 0 on failure, Post ID on success.
  */
 function wp_update_post($postarr = array()) {
 	if ( is_object($postarr) )
@@ -1558,17 +1539,14 @@ function wp_update_post($postarr = array()) {
 }
 
 /**
- * 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}}
+ * @param int $post_id Post ID.
+ * @return null
  */
 function wp_publish_post($post_id) {
 	global $wpdb;
@@ -1599,19 +1577,15 @@ function wp_publish_post($post_id) {
 }
 
 /**
- * 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 +1601,31 @@ function check_and_publish_future_post($post_id) {
 }
 
 /**
- * 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 +1643,16 @@ function wp_set_post_tags( $post_id = 0, $tags = '', $append = false ) {
 }
 
 /**
- * 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 +1666,27 @@ function wp_set_post_categories($post_ID = 0, $post_categories = array()) {
 	$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 +1701,14 @@ function wp_transition_post_status($new_status, $old_status, $post) {
 //
 
 /**
- * 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 +1724,13 @@ function add_ping($post_id, $uri) {
 }
 
 /**
- * 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 +1751,13 @@ function get_enclosed($post_id) {
 }
 
 /**
- * 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 +1769,13 @@ function get_pung($post_id) {
 }
 
 /**
- * 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 +1787,15 @@ function get_to_ping($post_id) {
 }
 
 /**
- * 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 +1803,7 @@ function trackback_url_list($tb_list, $post_id) {
 		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 +1811,10 @@ function trackback_url_list($tb_list, $post_id) {
 
 		$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 +1822,12 @@ function trackback_url_list($tb_list, $post_id) {
 //
 
 /**
- * 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 +1841,14 @@ function get_all_page_ids() {
 }
 
 /**
- * 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 +1864,14 @@ function &get_page(&$page, $output = OBJECT, $filter = 'raw') {
 }
 
 /**
- * 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 +1888,7 @@ function get_page_by_path($page_path, $output = OBJECT) {
 	$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 +1902,18 @@ function get_page_by_path($page_path, $output = OBJECT) {
 			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,21 +1921,21 @@ function get_page_by_title($page_title, $output = OBJECT) {
 	if ( $page )
 		return get_page($page, $output);
 
-	return NULL;
+	return null;
 }
 
 /**
- * get_page_children() - Retrieve child pages
+ * Retrieve child pages from list of pages matching page ID.
  *
- * {@internal Missing Long Description}}
+ * Matches against the pages parameter against the page ID. Also matches all
+ * children for the same to retrieve all children of a page. Does not make any
+ * SQL queries to get the children.
  *
- * @package WordPress
- * @subpackage Post
  * @since 1.5.1
  *
- * @param int $page_id page ID
- * @param array $pages list of pages
- * @return array {@internal Missing Description}}
+ * @param int $page_id Page ID.
+ * @param array $pages List of pages' objects.
+ * @return array
  */
 function &get_page_children($page_id, $pages) {
 	$page_list = array();
@@ -2010,18 +1950,16 @@ function &get_page_children($page_id, $pages) {
 }
 
 /**
- * get_page_hierarchy() - {@internal Missing Short Description}}
+ * Order the pages with children under parents in a flat list.
  *
- * Fetches the pages returned as a FLAT list, but arranged in order of their hierarchy,
- * i.e., child parents immediately follow their parents.
+ * Fetches the pages returned as a FLAT list, but arranged in order of their
+ * hierarchy, i.e., child parents immediately follow their parents.
  *
- * @package WordPress
- * @subpackage Post
- * @since 2.0
+ * @since 2.0.0
  *
- * @param array $posts posts array
- * @param int $parent parent page ID
- * @return array {@internal Missing Description}}
+ * @param array $posts Posts array.
+ * @param int $parent Parent page ID.
+ * @return array
  */
 function get_page_hierarchy($posts, $parent = 0) {
 	$result = array ( );
@@ -2036,16 +1974,14 @@ function get_page_hierarchy($posts, $parent = 0) {
 }
 
 /**
- * get_page_uri() - Builds a page URI
+ * Builds URI for a page.
  *
- * {@internal Missing Long Description}}
+ * Sub pages will be in the "directory" under the parent page post name.
  *
- * @package WordPress
- * @subpackage Post
- * @since 1.5
+ * @since 1.5.0
  *
- * @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 +2000,16 @@ function get_page_uri($page_id) {
 }
 
 /**
- * get_pages() - Retrieve a list of pages
+ * Retrieve a list of pages.
  *
- * {@internal Missing Long Description}}
+ * The defaults that can be overridden are the following: 'child_of',
+ * 'sort_order', 'sort_column', 'post_title', 'hierarchical', 'exclude',
+ * 'include', 'meta_key', 'meta_value', and 'authors'.
  *
- * @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 = '') {
@@ -2161,7 +2097,7 @@ function &get_pages($args = '') {
 	if ( ! empty( $meta_key ) || ! empty( $meta_value ) ) {
 		$join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )";
 
-		// meta_key and met_value might be slashed
+		// meta_key and meta_value might be slashed
 		$meta_key = stripslashes($meta_key);
 		$meta_value = stripslashes($meta_value);
 		if ( ! empty( $meta_key ) )
@@ -2198,16 +2134,12 @@ function &get_pages($args = '') {
 //
 
 /**
- * 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}}
- *
- * @package WordPress
- * @subpackage Post
- * @since 2.0
+ * @since 2.0.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,21 +2155,47 @@ function is_local_attachment($url) {
 }
 
 /**
- * wp_insert_attachment() - Insert an attachment
+ * Insert an attachment.
  *
- * {@internal Missing Long Description}}
+ * If you set the 'ID' in the $object parameter, it will mean that you are
+ * updating and attempt to update the attachment. You can also set the
+ * attachment name or title by setting the key 'post_name' or 'post_title'.
  *
- * @package WordPress
- * @subpackage Post
- * @since 2.0
+ * You can set the dates for the attachment manually by setting the 'post_date'
+ * and 'post_date_gmt' keys' values.
  *
+ * By default, the comments will use the default settings for whether the
+ * comments are allowed. You can close them manually or keep them open by
+ * setting the value for the 'comment_status' key.
+ *
+ * The $object parameter can have the following:
+ *     'post_status' - Default is 'draft'. Can not be override, set the same as
+ *         parent post.
+ *     'post_type' - Default is 'post', will be set to attachment. Can not
+ *         override.
+ *     'post_author' - Default is current user ID. The ID of the user, who added
+ *         the attachment.
+ *     'ping_status' - Default is the value in default ping status option.
+ *         Whether the attachment can accept pings.
+ *     'post_parent' - Default is 0. Can use $parent parameter or set this for
+ *         the post it belongs to, if any.
+ *     'menu_order' - Default is 0. The order it is displayed.
+ *     'to_ping' - Whether to ping.
+ *     'pinged' - Default is empty string.
+ *     'post_password' - Default is empty string. The password to access the
+ *         attachment.
+ *     'guid' - Global Unique ID for referencing the attachment.
+ *     'post_content_filtered' - Attachment post content filtered.
+ *     'post_excerpt' - Attachment excerpt.
+ *
+ * @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
- * @return int {@internal Missing Description}}
+ * @param string|array $object Arguments to override defaults.
+ * @param string $file Optional filename.
+ * @param int $post_parent Parent post ID.
+ * @return int Attachment ID.
  */
 function wp_insert_attachment($object, $file = false, $parent = 0) {
 	global $wpdb, $user_ID;
@@ -2300,9 +2258,9 @@ function wp_insert_attachment($object, $file = false, $parent = 0) {
 		$post_date_gmt = current_time('mysql', 1);
 
 	if ( empty($post_modified) )
-                $post_modified = $post_date;
+		$post_modified = $post_date;
 	if ( empty($post_modified_gmt) )
-                $post_modified_gmt = $post_date_gmt;
+		$post_modified_gmt = $post_date_gmt;
 
 	if ( empty($comment_status) ) {
 		if ( $update )
@@ -2367,17 +2325,18 @@ function wp_insert_attachment($object, $file = false, $parent = 0) {
 }
 
 /**
- * wp_delete_attachment() - Delete an attachment
+ * Delete an attachment.
  *
- * {@internal Missing Long Description}}
+ * Will remove the file also, when the attachment is removed. Removes all post
+ * meta fields, taxonomy, comments, etc associated with the attachment (except
+ * the main post).
  *
- * @package WordPress
- * @subpackage Post
- * @since 2.0
+ * @since 2.0.0
  * @uses $wpdb
+ * @uses do_action() Calls 'delete_attachment' hook on Attachment ID.
  *
- * @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 +2390,13 @@ function wp_delete_attachment($postid) {
 }
 
 /**
- * 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 +2410,13 @@ function wp_get_attachment_metadata( $post_id, $unfiltered = false ) {
 }
 
 /**
- * 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}}
+ * @param int $post_id Attachment ID.
+ * @param array $data Attachment data.
+ * @return int
  */
 function wp_update_attachment_metadata( $post_id, $data ) {
 	$post_id = (int) $post_id;
@@ -2478,16 +2429,12 @@ function wp_update_attachment_metadata( $post_id, $data ) {
 }
 
 /**
- * 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 +2450,12 @@ function wp_get_attachment_url( $post_id = 0 ) {
 }
 
 /**
- * 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 +2472,12 @@ function wp_get_attachment_thumb_file( $post_id = 0 ) {
 }
 
 /**
- * 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 +2499,12 @@ function wp_get_attachment_thumb_url( $post_id = 0 ) {
 }
 
 /**
- * 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,16 +2524,12 @@ function wp_attachment_is_image( $post_id = 0 ) {
 }
 
 /**
- * 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}}
+ * @return string|bool
  */
 function wp_mime_type_icon( $mime = 0 ) {
 	if ( !is_numeric($mime) )
@@ -2679,15 +2610,22 @@ function wp_mime_type_icon( $mime = 0 ) {
 }
 
 /**
- * wp_check_for_changed_slugs() - {@internal Missing Short Description}}
+ * Checked for changed slugs for published posts and save old slug.
  *
- * {@internal Missing Long Description}}
+ * The function is used along with form POST data. It checks for the wp-old-slug
+ * POST field. Will only be concerned with published posts and the slug actually
+ * changing.
  *
- * @package WordPress
- * @subpackage Post
- * @since 2.1
+ * If the slug was changed and not already part of the old slugs then it will be
+ * added to the post meta field ('_wp_old_slug') for storing old slugs for that
+ * post.
  *
- * @param int $post_id The Post ID
+ * The most logically usage of this function is redirecting changed posts, so
+ * that those that linked to an changed post will be redirected to the new post.
+ *
+ * @since 2.1.0
+ *
+ * @param int $post_id Post ID.
  * @return int Same as $post_id
  */
 function wp_check_for_changed_slugs($post_id) {
@@ -2718,20 +2656,21 @@ function wp_check_for_changed_slugs($post_id) {
 }
 
 /**
- * get_private_posts_cap_sql() - {@internal Missing Short Description}}
+ * Retrieve the private post SQL based on capability.
  *
- * 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
+ * It also allows plugins that define their own post type to control the cap by
+ * using the hook 'pub_priv_sql_capability'. The plugin is expected to return
+ * the capability the user must have to read the private post type.
+ *
+ * @since 2.2.0
  *
  * @uses $user_ID
- * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types
+ * @uses apply_filters() Call 'pub_priv_sql_capability' filter for plugins with different post types.
  *
  * @param string $post_type currently only supports 'post' or 'page'.
  * @return string SQL code that can be added to a where clause.
@@ -2773,12 +2712,12 @@ function get_private_posts_cap_sql($post_type) {
 }
 
 /**
- * get_lastpostdate() - {@internal Missing Short Description}}
+ * Retrieve the date the the last post was published.
  *
- * {@internal Missing Long Description}}
+ * The server timezone is the default and is the difference between GMT and
+ * server time. The 'blog' value is the date when the last post was posted. The
+ * 'gmt' is when the last post was posted in GMT formatted date.
  *
- * @package WordPress
- * @subpackage Post
  * @since 0.71
  *
  * @uses $wpdb
@@ -2814,20 +2753,18 @@ function get_lastpostdate($timezone = 'server') {
 }
 
 /**
- * get_lastpostmodified() - {@internal Missing Short Description}}
+ * Retrieve last post modified date depending on timezone.
  *
- * {@internal Missing Long Description}}
- *
- * @package WordPress
- * @subpackage Post
- * @since 1.2
+ * The server timezone is the default and is the difference between GMT and
+ * server time. The 'blog' value is just when the last post was modified. The
+ * 'gmt' is when the last post was modified in GMT time.
  *
+ * @since 1.2.0
  * @uses $wpdb
  * @uses $blog_id
  * @uses apply_filters() Calls 'get_lastpostmodified' filter
  *
  * @global mixed $cache_lastpostmodified Stores the date the last post was modified
- * @global mixed $pagenow The current page being viewed
  *
  * @param string $timezone The location to get the time. Can be 'gmt', 'blog', or 'server'.
  * @return string The date the post was last modified.
@@ -2859,9 +2796,9 @@ function get_lastpostmodified($timezone = 'server') {
 }
 
 /**
- * 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 +2815,14 @@ function update_post_cache(&$posts) {
 }
 
 /**
- * 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 +2848,7 @@ function clean_post_cache($id) {
 }
 
 /**
- * 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,14 +2863,14 @@ function update_page_cache(&$pages) {
 }
 
 /**
- * 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
- * @since 2.0
+ * @since 2.0.0
  *
  * @uses do_action() Will call the 'clean_page_cache' hook action.
  *
@@ -2949,11 +2886,11 @@ function clean_page_cache($id) {
 }
 
 /**
- * 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()
@@ -2980,18 +2917,20 @@ function update_post_caches(&$posts) {
 }
 
 /**
- * update_postmeta_cache() - {@internal Missing Short Description}}
+ * Updates metadata cache for list of post IDs.
  *
- * {@internal Missing Long Description}}
+ * Performs SQL query to retrieve the metadata for the post IDs and updates the
+ * metadata cache for the posts. Therefore, the functions, which call this
+ * function, do not need to perform SQL queries on their own.
  *
  * @package WordPress
  * @subpackage Cache
- * @since 2.1
+ * @since 2.1.0
  *
  * @uses $wpdb
  *
- * @param array $post_ids {@internal Missing Description}}
- * @return bool|array Returns false if there is nothing to update or an array of metadata
+ * @param array $post_ids List of post IDs.
+ * @return bool|array Returns false if there is nothing to update or an array of metadata.
  */
 function update_postmeta_cache($post_ids) {
 	global $wpdb;
@@ -3051,18 +2990,14 @@ function update_postmeta_cache($post_ids) {
 //
 
 /**
- * _transition_post_status() - Hook {@internal Missing Short Description}}
- *
- * {@internal Missing Long Description}}
- *
- * @package WordPress
- * @subpackage Post
- * @since 2.3
+ * Hook for managing future post transitions to published.
  *
+ * @since 2.3.0
+ * @access private
  * @uses $wpdb
  *
- * @param string $new_status {@internal Missing Description}}
- * @param string $old_status {@internal Missing Description}}
+ * @param string $new_status New post status
+ * @param string $old_status Previous post status
  * @param object $post Object type containing the post information
  */
 function _transition_post_status($new_status, $old_status, $post) {
@@ -3080,15 +3015,13 @@ function _transition_post_status($new_status, $old_status, $post) {
 }
 
 /**
- * _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 int $deprecated Not Used. Can be set to null.
  * @param object $post Object type containing the post information
  */
 function _future_post_hook($deprecated = '', $post) {
@@ -3097,14 +3030,9 @@ function _future_post_hook($deprecated = '', $post) {
 }
 
 /**
- * _publish_post_hook() - Hook {@internal Missing Short Description}}
- *
- * {@internal Missing Long Description}}
- *
- * @package WordPress
- * @subpackage Post
- * @since 2.3
+ * Hook to schedule pings and enclosures when a post is published.
  *
+ * @since 2.3.0
  * @uses $wpdb
  * @uses XMLRPC_REQUEST
  * @uses APP_REQUEST
@@ -3132,19 +3060,18 @@ function _publish_post_hook($post_id) {
 }
 
 /**
- * _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
- * that the cache updates to the changes done recently. For pages, the rewrite rules of
- * WordPress are flushed to allow for any changes.
+ * 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 that the cache updates to the changes done
+ * recently. For pages, the rewrite rules of WordPress are flushed to allow for
+ * any changes.
  *
- * The $post parameter, only uses 'post_type' property and 'page_template' property.
- *
- * @package WordPress
- * @subpackage Post
- * @since 2.3
+ * The $post parameter, only uses 'post_type' property and 'page_template'
+ * property.
  *
+ * @since 2.3.0
  * @uses $wp_rewrite Flushes Rewrite Rules.
  *
  * @param int $post_id The ID in the database table for the $post
@@ -3160,10 +3087,25 @@ function _save_post_hook($post_id, $post) {
 	}
 }
 
-//
-// Private
-//
-
+/**
+ * Retrieve post ancestors and append to post ancestors property.
+ *
+ * Will only retrieve ancestors once, if property is already set, then nothing
+ * will be done. If there is not a parent post, or post ID and post parent ID
+ * are the same then nothing will be done.
+ *
+ * The parameter is passed by reference, so nothing needs to be returned. The
+ * property will be updated and can be referenced after the function is
+ * complete. The post parent will be an ancestor and the parent of the post
+ * parent will be an ancestor. There will only be two ancestors at the most.
+ *
+ * @access private
+ * @since unknown
+ * @uses $wpdb
+ *
+ * @param object $_post Post data.
+ * @return null When nothing needs to be done.
+ */
 function _get_post_ancestors(&$_post) {
 	global $wpdb;
 
@@ -3183,22 +3125,21 @@ function _get_post_ancestors(&$_post) {
 	}
 }
 
-/* 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 +3178,18 @@ function _wp_post_revision_fields( $post = null, $autosave = false ) {
 }
 
 /**
- * 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 +3233,17 @@ function wp_save_post_revision( $post_id ) {
 }
 
 /**
- * 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 +3270,28 @@ function wp_get_post_autosave( $post_id ) {
 	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 +3300,14 @@ function wp_is_post_revision( $post ) {
 }
 
 /**
- * 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 +3318,17 @@ function wp_is_post_autosave( $post ) {
 }
 
 /**
- * _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 +3353,18 @@ function _wp_put_post_revision( $post = null, $autosave = false ) {
 }
 
 /**
- * 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 +3387,21 @@ function &wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') {
 }
 
 /**
- * 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 +3430,20 @@ function wp_restore_post_revision( $revision_id, $fields = null ) {
 }
 
 /**
- * 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 +3460,15 @@ function wp_delete_post_revision( $revision_id ) {
 }
 
 /**
- * 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 ) {