Ticket #30230: 30230.diff

src/wp-admin/edit.php

@@ -62 +62 @@
                 $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 +56 @@
         '<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 +1142 @@
                         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 +1488 @@
 }
 
 /**
- * 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 +1619 @@
 }
 
 /**
- * Ajax handler for finding posts.
+ * Ajax handler for querying posts for the Find Posts modal.
+ *
+ * @see window.findPosts
  *
  * @since 3.1.0
  */
@@ -2147 +2151 @@
 }
 
 /**
- * Ajax handler for querying for attachments.
+ * Ajax handler for querying attachments.
  *
  * @since 3.5.0
  */
@@ -2193 +2197 @@
 }
 
 /**
- * Ajax handler for saving attachment attributes.
+ * Ajax handler for updating attachment attributes.
  *
  * @since 3.5.0
  */

src/wp-admin/includes/export.php

@@ -16 +16 @@
 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 +250 @@
 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 +1060 @@
 }
 
 /**
- * Get a list of all registered post status objects.
+ * Get a list of post statuses.
  *
  * @since 3.0.0
  *
@@ -1068 +1068 @@
  *
  * @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 +70 @@
 }
 
 /**
- * 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 +156 @@
 
         $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 +447 @@
 
 /**
  * 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 ) {