Changeset 47119 for trunk/src/wp-admin/includes/meta-boxes.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/meta-boxes.php (modified) (18 diffs)

trunk/src/wp-admin/includes/meta-boxes.php

@@ -1 +1 @@
 <?php
-
-// -- Post related Meta Boxes
+/**
+ * WordPress Administration Meta Boxes API.
+ *
+ * @package WordPress
+ * @subpackage Administration
+ */
+
+//
+// Post-related Meta Boxes.
+//
 
 /**
@@ -31 +39 @@
 <div id="minor-publishing">
 
-    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key ?>
+    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key. ?>
 <div style="display:none;">
     <?php submit_button( __( 'Save' ), '', 'save' ); ?>
@@ -72 +80 @@
 <input type="hidden" name="wp-preview" id="wp-preview" value="" />
 </div>
-<?php endif; // public post type ?>
+<?php endif; // is_post_type_viewable() ?>
     <?php
     /**
@@ -203 +211 @@
 
     if ( 0 != $post->ID ) {
-        if ( 'future' == $post->post_status ) { // scheduled for publishing at a future date
+        if ( 'future' == $post->post_status ) { // Scheduled for publishing at a future date.
             /* translators: Post date information. %s: Date on which the post is currently scheduled to be published. */
             $stamp = __( 'Scheduled for: %s' );
-        } elseif ( 'publish' == $post->post_status || 'private' == $post->post_status ) { // already published
+        } elseif ( 'publish' == $post->post_status || 'private' == $post->post_status ) { // Already published.
             /* translators: Post date information. %s: Date on which the post was published. */
             $stamp = __( 'Published on: %s' );
-        } elseif ( '0000-00-00 00:00:00' == $post->post_date_gmt ) { // draft, 1 or more saves, no date specified
+        } elseif ( '0000-00-00 00:00:00' == $post->post_date_gmt ) { // Draft, 1 or more saves, no date specified.
             $stamp = __( 'Publish <b>immediately</b>' );
-        } elseif ( time() < strtotime( $post->post_date_gmt . ' +0000' ) ) { // draft, 1 or more saves, future date specified
+        } elseif ( time() < strtotime( $post->post_date_gmt . ' +0000' ) ) { // Draft, 1 or more saves, future date specified.
             /* translators: Post date information. %s: Date on which the post is to be published. */
             $stamp = __( 'Schedule for: %s' );
-        } else { // draft, 1 or more saves, date specified
+        } else { // Draft, 1 or more saves, date specified.
             /* translators: Post date information. %s: Date on which the post is to be published. */
             $stamp = __( 'Publish on: %s' );
@@ -223 +231 @@
             date_i18n( $time_format, strtotime( $post->post_date ) )
         );
-    } else { // draft (no saves, and thus no date specified)
+    } else { // Draft (no saves, and thus no date specified).
         $stamp = __( 'Publish <b>immediately</b>' );
         $date  = sprintf(
@@ -244 +252 @@
 endif;
 
-    if ( $can_publish ) : // Contributors don't get to choose the date of publish
+    if ( $can_publish ) : // Contributors don't get to choose the date of publish.
         ?>
 <div class="misc-pub-section curtime misc-pub-curtime">
@@ -372 +380 @@
 <div id="minor-publishing">
 
-    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key ?>
+    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key. ?>
 <div style="display:none;">
     <?php submit_button( __( 'Save' ), '', 'save' ); ?>
@@ -463 +471 @@
                 $post_format = '0';
             }
-            // Add in the current one if it isn't there yet, in case the current theme doesn't support it
+            // Add in the current one if it isn't there yet, in case the current theme doesn't support it.
             if ( $post_format && ! in_array( $post_format, $post_formats[0] ) ) {
                 $post_formats[0][] = $post_format;
@@ -592 +600 @@
             <?php
             $name = ( $tax_name == 'category' ) ? 'post_category' : 'tax_input[' . $tax_name . ']';
-            echo "<input type='hidden' name='{$name}[]' value='0' />"; // Allows for an empty term set to be sent. 0 is an invalid Term ID and will be ignored by empty() checks.
+            // Allows for an empty term set to be sent. 0 is an invalid term ID and will be ignored by empty() checks.
+            echo "<input type='hidden' name='{$name}[]' value='0' />";
             ?>
             <ul id="<?php echo $tax_name; ?>checklist" data-wp-lists="list:<?php echo $tax_name; ?>" class="categorychecklist form-no-clear">
@@ -793 +802 @@
      * @param WP_Post $post WP_Post object of the current post.
      */
-    do_action( 'post_comment_status_meta_box-options', $post );  // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
+    do_action( 'post_comment_status_meta_box-options', $post ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
     ?>
 </p>
@@ -904 +913 @@
 }
 
-// -- Page related Meta Boxes
+//
+// Page-related Meta Boxes.
+//
 
 /**
@@ -942 +953 @@
             <?php echo $pages; ?>
             <?php
-        endif; // end empty pages check
-    endif;  // end hierarchical check.
+        endif; // End empty pages check.
+    endif;  // End hierarchical check.
 
     if ( count( get_page_templates( $post ) ) > 0 && get_option( 'page_for_posts' ) != $post->ID ) :
@@ -999 +1010 @@
 }
 
-// -- Link related Meta Boxes
+//
+// Link-related Meta Boxes.
+//
 
 /**
@@ -1014 +1027 @@
 <div id="minor-publishing">
 
-    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key ?>
+    <?php // Hidden submit button early on so that the browser chooses the right button when form is submitted with Return key. ?>
 <div style="display:none;">
     <?php submit_button( __( 'Save' ), '', 'save', false ); ?>
@@ -1164 +1177 @@
 
     if ( ! empty( $deprecated ) ) {
-        _deprecated_argument( __FUNCTION__, '2.5.0' ); // Never implemented
+        _deprecated_argument( __FUNCTION__, '2.5.0' ); // Never implemented.
     }
 
@@ -1414 +1427 @@
         // We should aim to show the revisions meta box only when there are revisions.
         if ( count( $revisions ) > 1 ) {
-            reset( $revisions ); // Reset pointer for key()
+            reset( $revisions ); // Reset pointer for key().
             $publish_callback_args = array(
                 'revisions_count'        => count( $revisions ),
@@ -1441 +1454 @@
     }
 
-    // all taxonomies
+    // All taxonomies.
     foreach ( get_object_taxonomies( $post ) as $tax_name ) {
         $taxonomy = get_taxonomy( $tax_name );
@@ -1524 +1537 @@
 
     if ( in_array( get_post_status( $post ), $stati ) ) {
-        // If the post type support comments, or the post has comments, allow the
-        // Comments meta box.
+        // If the post type support comments, or the post has comments,
+        // allow the Comments meta box.
         if ( comments_open( $post ) || pings_open( $post ) || $post->comment_count > 0 || post_type_supports( $post_type, 'comments' ) ) {
             add_meta_box( 'commentsdiv', __( 'Comments' ), 'post_comment_meta_box', null, 'normal', 'core', array( '__back_compat_meta_box' => true ) );