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-admin/edit.php

@@ -62,9 +62,12 @@ if ( $doaction ) {
 		$sendback = admin_url($post_new_file);
 
 	if ( 'delete_all' == $doaction ) {
+		// Prepare for deletion of all posts with a specified post status (i.e. Empty trash).
 		$post_status = preg_replace('/[^a-z0-9_-]+/i', '', $_REQUEST['post_status']);
-		if ( get_post_status_object($post_status) ) // Check the post status exists first
+		// Validate the post status exists.
+		if ( get_post_status_object( $post_status ) ) {
 			$post_ids = $wpdb->get_col( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_type=%s AND post_status = %s", $post_type, $post_status ) );
+		}
 		$doaction = 'delete';
 	} elseif ( isset( $_REQUEST['media'] ) ) {
 		$post_ids = $_REQUEST['media'];

src/wp-admin/export.php

@@ -56,6 +56,7 @@ get_current_screen()->set_help_sidebar(
 	'<p>' . __('<a href="https://wordpress.org/support/" target="_blank">Support Forums</a>') . '</p>'
 );
 
+// If the 'download' URL parameter is set, a WXR export file is baked and returned.
 if ( isset( $_GET['download'] ) ) {
 	$args = array();
 

src/wp-admin/includes/ajax-actions.php

@@ -1142,6 +1142,9 @@ function wp_ajax_add_meta() {
 			wp_die( -1 );
 		if ( isset($_POST['metakeyselect']) && '#NONE#' == $_POST['metakeyselect'] && empty($_POST['metakeyinput']) )
 			wp_die( 1 );
+		
+		// If the post is an autodraft, save the post as a draft and then
+		// attempt to save the meta.
 		if ( $post->post_status == 'auto-draft' ) {
 			$save_POST = $_POST; // Backup $_POST
 			$_POST = array(); // Make it empty for edit_post()
@@ -1486,7 +1489,7 @@ function wp_ajax_sample_permalink() {
 }
 
 /**
- * Ajax handler for quick edit saving for a post.
+ * Ajax handler for Quick Edit saving a post from a list table.
  *
  * @since 3.1.0
  */
@@ -1617,7 +1620,9 @@ function wp_ajax_inline_save_tax() {
 }
 
 /**
- * Ajax handler for finding posts.
+ * Ajax handler for querying posts for the Find Posts modal.
+ *
+ * @see window.findPosts
  *
  * @since 3.1.0
  */
@@ -2147,7 +2152,7 @@ function wp_ajax_get_attachment() {
 }
 
 /**
- * Ajax handler for querying for attachments.
+ * Ajax handler for querying attachments.
  *
  * @since 3.5.0
  */
@@ -2193,7 +2198,7 @@ function wp_ajax_query_attachments() {
 }
 
 /**
- * Ajax handler for saving attachment attributes.
+ * Ajax handler for updating attachment attributes.
  *
  * @since 3.5.0
  */

src/wp-admin/includes/export.php

@@ -16,11 +16,11 @@
 define( 'WXR_VERSION', '1.2' );
 
 /**
- * Generates the WXR export file for download
+ * Generates the WXR export file for download.
  *
  * @since 2.1.0
  *
- * @param array $args Filters defining what should be included in the export
+ * @param array $args Filters defining what should be included in the export.
  */
 function export_wp( $args = array() ) {
 	global $wpdb, $post;

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 array|string $args     Optional. Array or string of post status arguments to compare against
- * @param string       $output   Optional. The type of output to return. Accepts post status 'names'
+ *                               properties of the global $wp_post_statuses objects. Default empty array.
- *                               or 'objects'. Default 'names'.
+ * @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,10 +70,10 @@ 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.
+ * Typically used immediately after a post update, as every update is a revision,
- * Adds a copy of the current post as a revision, so latest revision always matches current post
+ * and the most recent revision always matches the current post.
  *
  * @since 2.6.0
  *
@@ -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,7 +447,11 @@ 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
  *