Changeset 47119 for trunk/src/wp-admin/includes/post.php

Timestamp:

01/29/2020 12:33:45 AM (7 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve comments in some wp-admin files per the documentation standards.

Follow-up to [47084].

Props passoniate, apedog.
Fixes #49223, #49227.

File:

• trunk/src/wp-admin/includes/post.php (modified) (31 diffs)

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

@@ -93 +93 @@
                 $post_data['post_status'] = sanitize_key( $post_data['post_status'] );
 
-                // No longer an auto-draft
+                // No longer an auto-draft.
                 if ( 'auto-draft' === $post_data['post_status'] ) {
                         $post_data['post_status'] = 'draft';
@@ -103 +103 @@
         }
 
-        // What to do based on which button they pressed
+        // What to do based on which button they pressed.
         if ( isset( $post_data['saveasdraft'] ) && '' != $post_data['saveasdraft'] ) {
                 $post_data['post_status'] = 'draft';
@@ -133 +133 @@
         $published_statuses = array( 'publish', 'future' );
 
-        // Posts 'submitted for approval' present are submitted to $_POST the same as if they were being published.
+        // Posts 'submitted for approval' are submitted to $_POST the same as if they were being published.
         // Change status from 'publish' to 'pending' if user lacks permissions to publish or to resave published posts.
         if ( isset( $post_data['post_status'] ) && ( in_array( $post_data['post_status'], $published_statuses ) && ! current_user_can( $ptype->cap->publish_posts ) ) ) {
@@ -209 +209 @@
         }
 
-        // Pass through errors
+        // Pass through errors.
         if ( is_wp_error( $post_data ) ) {
                 return $post_data;
@@ -269 +269 @@
                 $revision  = current( $revisions );
 
-                // Check if the revisions have been upgraded
+                // Check if the revisions have been upgraded.
                 if ( $revisions && _wp_get_post_revision_version( $revision ) < 1 ) {
                         _wp_upgrade_revisions_of_post( $post, wp_get_post_revisions( $post_ID ) );
@@ -297 +297 @@
         $translated = _wp_get_allowed_postdata( $post_data );
 
-        // Post Formats
+        // Post formats.
         if ( isset( $post_data['post_format'] ) ) {
                 set_post_format( $post_ID, $post_data['post_format'] );
@@ -337 +337 @@
         }
 
-        // Meta Stuff
+        // Meta stuff.
         if ( isset( $post_data['meta'] ) && $post_data['meta'] ) {
                 foreach ( $post_data['meta'] as $key => $value ) {
@@ -373 +373 @@
         }
 
-        // Attachment stuff
+        // Attachment stuff.
         if ( 'attachment' == $post_data['post_type'] ) {
                 if ( isset( $post_data['_wp_attachment_image_alt'] ) ) {
                         $image_alt = wp_unslash( $post_data['_wp_attachment_image_alt'] );
+
                         if ( $image_alt != get_post_meta( $post_ID, '_wp_attachment_image_alt', true ) ) {
                                 $image_alt = wp_strip_all_tags( $image_alt, true );
-                                // update_meta expects slashed.
+
+                                // update_post_meta() expects slashed.
                                 update_post_meta( $post_ID, '_wp_attachment_image_alt', wp_slash( $image_alt ) );
                         }
@@ -406 +408 @@
 
         $success = wp_update_post( $translated );
-        // If the save failed, see if we can sanity check the main fields and try again
+
+        // If the save failed, see if we can sanity check the main fields and try again.
         if ( ! $success && is_callable( array( $wpdb, 'strip_invalid_text_for_column' ) ) ) {
                 $fields = array( 'post_title', 'post_content', 'post_excerpt' );
@@ -419 +422 @@
         }
 
-        // Now that we have an ID we can fix any attachment anchor hrefs
+        // Now that we have an ID we can fix any attachment anchor hrefs.
         _fix_attachment_links( $post_ID );
 
@@ -677 +680 @@
                 }
 
-                // Schedule auto-draft cleanup
+                // Schedule auto-draft cleanup.
                 if ( ! wp_next_scheduled( 'wp_scheduled_auto_draft_delete' ) ) {
                         wp_schedule_event( time(), 'daily', 'wp_scheduled_auto_draft_delete' );
@@ -817 +820 @@
         unset( $_POST['filter'] );
 
-        // Edit don't write if we have a post id.
+        // Edit, don't write, if we have a post ID.
         if ( isset( $_POST['post_ID'] ) ) {
                 return edit_post();
@@ -858 +861 @@
         add_post_meta( $post_ID, '_edit_last', $GLOBALS['current_user']->ID );
 
-        // Now that we have an ID we can fix any attachment anchor hrefs
+        // Now that we have an ID we can fix any attachment anchor hrefs.
         _fix_attachment_links( $post_ID );
 
@@ -883 +886 @@
 
 //
-// Post Meta
+// Post Meta.
 //
 
@@ -914 +917 @@
 
                 if ( $metakeyinput ) {
-                        $metakey = $metakeyinput; // default
+                        $metakey = $metakeyinput; // Default.
                 }
 
@@ -927 +930 @@
 
         return false;
-} // add_meta
+}
 
 /**
@@ -1018 +1021 @@
 
 //
-// Private
+// Private.
 //
 
@@ -1039 +1042 @@
         }
 
-        // Short if there aren't any links or no '?attachment_id=' strings (strpos cannot be zero)
+        // Short if there aren't any links or no '?attachment_id=' strings (strpos cannot be zero).
         if ( ! strpos( $content, '?attachment_id=' ) || ! preg_match_all( '/<a ([^>]+)>[\s\S]+?<\/a>/', $content, $link_matches ) ) {
                 return;
@@ -1045 +1048 @@
 
         $site_url = get_bloginfo( 'url' );
-        $site_url = substr( $site_url, (int) strpos( $site_url, '://' ) ); // remove the http(s)
+        $site_url = substr( $site_url, (int) strpos( $site_url, '://' ) ); // Remove the http(s).
         $replace  = '';
 
@@ -1055 +1058 @@
                 }
 
-                $quote  = $url_match[1]; // the quote (single or double)
+                $quote  = $url_match[1]; // The quote (single or double).
                 $url_id = (int) $url_match[2];
                 $rel_id = (int) $rel_match[1];
@@ -1345 +1348 @@
         }
 
-        // If the user wants to set a new name -- override the current one
-        // Note: if empty name is supplied -- use the title instead, see #6072
+        // If the user wants to set a new name -- override the current one.
+        // Note: if empty name is supplied -- use the title instead, see #6072.
         if ( ! is_null( $name ) ) {
                 $post->post_name = sanitize_title( $name ? $name : $title, $post->ID );
@@ -1357 +1360 @@
         $permalink = get_permalink( $post, true );
 
-        // Replace custom post_type Token with generic pagename token for ease of use.
+        // Replace custom post_type token with generic pagename token for ease of use.
         $permalink = str_replace( "%$post->post_type%", '%pagename%', $permalink );
 
-        // Handle page hierarchy
+        // Handle page hierarchy.
         if ( $ptype->hierarchical ) {
                 $uri = get_page_uri( $post );
@@ -1432 +1435 @@
                                 $view_link = get_permalink( $post );
                         } else {
-                                // Allow non-published (private, future) to be viewed at a pretty permalink, in case $post->post_name is set
+                                // Allow non-published (private, future) to be viewed at a pretty permalink, in case $post->post_name is set.
                                 $view_link = str_replace( array( '%pagename%', '%postname%' ), $post->post_name, $permalink );
                         }
@@ -1438 +1441 @@
         }
 
-        // Permalinks without a post/page name placeholder don't have anything to edit
+        // Permalinks without a post/page name placeholder don't have anything to edit.
         if ( false === strpos( $permalink, '%postname%' ) && false === strpos( $permalink, '%pagename%' ) ) {
                 $return = '<strong>' . __( 'Permalink:' ) . "</strong>\n";
@@ -1449 +1452 @@
                 }
 
-                // Encourage a pretty permalink setting
+                // Encourage a pretty permalink setting.
                 if ( '' == get_option( 'permalink_structure' ) && current_user_can( 'manage_options' ) && ! ( 'page' == get_option( 'show_on_front' ) && $id == get_option( 'page_on_front' ) ) ) {
                         $return .= '<span id="change-permalinks"><a href="options-permalink.php" class="button button-small" target="_blank">' . __( 'Change Permalinks' ) . "</a></span>\n";
@@ -1693 +1696 @@
                 if ( get_post_type_object( $post->post_type )->public ) {
                         if ( 'publish' == $post->post_status || $user->ID != $post->post_author ) {
-                                // Latest content is in autosave
+                                // Latest content is in autosave.
                                 $nonce                       = wp_create_nonce( 'post_preview_' . $post->ID );
                                 $query_args['preview_id']    = $post->ID;
@@ -1748 +1751 @@
                 }
 
-                // Allow plugins to prevent some users overriding the post lock
+                // Allow plugins to prevent some users overriding the post lock.
                 if ( $override ) {
                         ?>
@@ -1820 +1823 @@
                 $new_autosave['post_author'] = $post_author;
 
+                $post = get_post( $post_id );
+
                 // If the new autosave has the same content as the post, delete the autosave.
-                $post                  = get_post( $post_id );
                 $autosave_is_different = false;
                 foreach ( array_intersect( array_keys( $new_autosave ), array_keys( _wp_post_revision_fields( $post ) ) ) as $field ) {
@@ -1850 +1854 @@
         $post_data = wp_unslash( $post_data );
 
-        // Otherwise create the new autosave as a special post revision
+        // Otherwise create the new autosave as a special post revision.
         return _wp_put_post_revision( $post_data, true );
 }
@@ -1923 +1927 @@
  */
 function wp_autosave( $post_data ) {
-        // Back-compat
+        // Back-compat.
         if ( ! defined( 'DOING_AUTOSAVE' ) ) {
                 define( 'DOING_AUTOSAVE', true );
@@ -1951 +1955 @@
 
         if ( ! wp_check_post_lock( $post->ID ) && get_current_user_id() == $post->post_author && ( 'auto-draft' == $post->post_status || 'draft' == $post->post_status ) ) {
-                // Drafts and auto-drafts are just overwritten by autosave for the same user if the post is not locked
+                // Drafts and auto-drafts are just overwritten by autosave for the same user if the post is not locked.
                 return edit_post( wp_slash( $post_data ) );
         } else {
-                // Non drafts or other users drafts are not overwritten. The autosave is stored in a special post revision for each user.
+                // Non-drafts or other users' drafts are not overwritten.
+                // The autosave is stored in a special post revision for each user.
                 return wp_create_post_autosave( wp_slash( $post_data ) );
         }