Improve some post_status-related documentation.

Props ericlewis.
See #30230.


git-svn-id: https://develop.svn.wordpress.org/trunk@30155 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/default-filters.php

@@ -250,6 +250,7 @@ add_action( 'init',                       'smilies_init',
 add_action( 'plugins_loaded',             'wp_maybe_load_widgets',                    0    );
 add_action( 'plugins_loaded',             'wp_maybe_load_embeds',                     0    );
 add_action( 'shutdown',                   'wp_ob_end_flush_all',                      1    );
+// Create a revision whenever a post is updated.
 add_action( 'post_updated',               'wp_save_post_revision',                   10, 1 );
 add_action( 'publish_post',               '_publish_post_hook',                       5, 1 );
 add_action( 'transition_post_status',     '_transition_post_status',                  5, 3 );

src/wp-includes/post.php

@@ -1060,7 +1060,7 @@ function get_post_status_object( $post_status ) {
 }
 
 /**
- * Get a list of all registered post status objects.
+ * Get a list of post statuses.
  *
  * @since 3.0.0
  *
@@ -1068,9 +1068,9 @@ function get_post_status_object( $post_status ) {
  *
  * @see register_post_status()
  *
- * @param array|string $args     Optional. Array or string of post status arguments. Default array.
- * @param string       $output   Optional. The type of output to return. Accepts post status 'names'
- *                               or 'objects'. Default 'names'.
+ * @param array|string $args     Optional. Array or string of post status arguments to compare against
+ *                               properties of the global $wp_post_statuses objects. Default empty array.
+ * @param string       $output   Optional. The type of output to return, either 'names' or 'objects'. Default 'names'.
  * @param string       $operator Optional. The logical operation to perform. 'or' means only one element
  *                               from the array needs to match; 'and' means all elements must match.
  *                               Default 'and'.

src/wp-includes/revision.php

@@ -70,14 +70,14 @@ function _wp_post_revision_fields( $post = null, $autosave = false ) {
 }
 
 /**
- * Saves an already existing post as a post revision.
+ * Creates a revision for the current version of a post.
  *
- * Typically used immediately after post updates.
- * Adds a copy of the current post as a revision, so latest revision always matches current post
+ * Typically used immediately after a post update, as every update is a revision,
+ * and the most recent revision always matches the current post.
  *
  * @since 2.6.0
  *
- * @param int $post_id The ID of the post to save as a 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.
  */
 function wp_save_post_revision( $post_id ) {
@@ -156,12 +156,13 @@ function wp_save_post_revision( $post_id ) {
 
 	$return = _wp_put_post_revision( $post );
 
+	// If a limit for the number of revisions to keep has been set,
+	// delete the oldest ones.
 	$revisions_to_keep = wp_revisions_to_keep( $post );
 
 	if ( $revisions_to_keep < 0 )
 		return $return;
 
-	// all revisions and autosaves
 	$revisions = wp_get_post_revisions( $post_id, array( 'order' => 'ASC' ) );
 
 	$delete = count($revisions) - $revisions_to_keep;
@@ -446,11 +447,15 @@ function wp_revisions_enabled( $post ) {
 
 /**
  * Determine how many revisions to retain for a given post.
- * By default, an infinite number of revisions are stored if a post type supports revisions.
+ *
+ * By default, an infinite number of revisions are kept.
+ *
+ * The constant WP_POST_REVISIONS can be set in wp-config to specify the limit
+ * of revisions to keep.
  *
  * @since 3.6.0
  *
- * @param object $post The post object.
+ * @param  object $post The post object.
  * @return int The number of revisions to keep.
  */
 function wp_revisions_to_keep( $post ) {