Changeset 30155

Timestamp:

11/01/2014 08:19:26 PM (10 years ago)

Author:

wonderboymusic

Message:

Improve some post_status-related documentation.

Props ericlewis.
See #30230.

Location:

trunk/src

Files:

• wp-admin/edit.php (modified) (1 diff)
• wp-admin/export.php (modified) (1 diff)
• wp-admin/includes/ajax-actions.php (modified) (5 diffs)
• wp-admin/includes/export.php (modified) (1 diff)
• wp-includes/default-filters.php (modified) (1 diff)
• wp-includes/post.php (modified) (2 diffs)
• wp-includes/revision.php (modified) (4 diffs)

trunk/src/wp-admin/edit.php

@@ -63 +63 @@
 
     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'] ) ) {

trunk/src/wp-admin/export.php

@@ -57 +57 @@
 );
 
+// If the 'download' URL parameter is set, a WXR export file is baked and returned.
 if ( isset( $_GET['download'] ) ) {
     $args = array();

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

@@ -1143 +1143 @@
         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
@@ -1487 +1490 @@
 
 /**
- * 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
@@ -1618 +1621 @@
 
 /**
- * Ajax handler for finding posts.
+ * Ajax handler for querying posts for the Find Posts modal.
+ *
+ * @see window.findPosts
  *
  * @since 3.1.0
@@ -2148 +2153 @@
 
 /**
- * Ajax handler for querying for attachments.
+ * Ajax handler for querying attachments.
  *
  * @since 3.5.0
@@ -2194 +2199 @@
 
 /**
- * Ajax handler for saving attachment attributes.
+ * Ajax handler for updating attachment attributes.
  *
  * @since 3.5.0

trunk/src/wp-admin/includes/export.php

@@ -17 +17 @@
 
 /**
- * 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() ) {

trunk/src/wp-includes/default-filters.php

@@ -251 +251 @@
 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 );

trunk/src/wp-includes/post.php

@@ -1061 +1061 @@
 
 /**
- * Get a list of all registered post status objects.
+ * Get a list of post statuses.
  *
  * @since 3.0.0
@@ -1069 +1069 @@
  * @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.

trunk/src/wp-includes/revision.php

@@ -71 +71 @@
 
 /**
- * Saves an already existing post as a post revision.
- *
- * Typically used immediately after post updates.
- * Adds a copy of the current post as a revision, so latest revision always matches current post
- *
- * @since 2.6.0
- *
- * @param int $post_id The ID of the post to save as a revision.
+ * Creates a revision for the current version of a 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.
  * @return mixed Null or 0 if error, new revision ID, if success.
  */
@@ -157 +157 @@
     $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 );
 
@@ -162 +164 @@
         return $return;
 
-    // all revisions and autosaves
     $revisions = wp_get_post_revisions( $post_id, array( 'order' => 'ASC' ) );
 
@@ -447 +448 @@
 /**
  * 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.
  */