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

Timestamp:

01/29/2020 12:33:45 AM (5 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 ) );
     }