From c8acddfdc89cf3e0cbb7420bde7c9938f415ceeb Mon Sep 17 00:00:00 2001 From: Scott Taylor Date: Sat, 1 Nov 2014 20:19:26 +0000 Subject: [PATCH] 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 | 5 ++++- src/wp-admin/export.php | 1 + src/wp-admin/includes/ajax-actions.php | 13 +++++++++---- src/wp-admin/includes/export.php | 4 ++-- src/wp-includes/default-filters.php | 1 + src/wp-includes/post.php | 8 ++++---- src/wp-includes/revision.php | 19 ++++++++++++------- 7 files changed, 33 insertions(+), 18 deletions(-) diff --git a/src/wp-admin/edit.php b/src/wp-admin/edit.php index cba36d5686..de0b7d0f56 100644 --- a/src/wp-admin/edit.php +++ b/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']; diff --git a/src/wp-admin/export.php b/src/wp-admin/export.php index b066dc2238..78ccf13e10 100644 --- a/src/wp-admin/export.php +++ b/src/wp-admin/export.php @@ -56,6 +56,7 @@ get_current_screen()->set_help_sidebar( '

' . __('Support Forums') . '

' ); +// If the 'download' URL parameter is set, a WXR export file is baked and returned. if ( isset( $_GET['download'] ) ) { $args = array(); diff --git a/src/wp-admin/includes/ajax-actions.php b/src/wp-admin/includes/ajax-actions.php index c9b4563bc4..eea72944fc 100644 --- a/src/wp-admin/includes/ajax-actions.php +++ b/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 */ diff --git a/src/wp-admin/includes/export.php b/src/wp-admin/includes/export.php index 397e9e7a03..f5823d9160 100644 --- a/src/wp-admin/includes/export.php +++ b/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; diff --git a/src/wp-includes/default-filters.php b/src/wp-includes/default-filters.php index e4feb4f333..dc0c8f80d0 100644 --- a/src/wp-includes/default-filters.php +++ b/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 ); diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 7e6f662a69..31bf142f45 100644 --- a/src/wp-includes/post.php +++ b/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'. diff --git a/src/wp-includes/revision.php b/src/wp-includes/revision.php index 62f0fbc030..2661accd7f 100644 --- a/src/wp-includes/revision.php +++ b/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 ) {