Changeset 47122 for trunk/src/wp-includes/post-template.php

Timestamp:

01/29/2020 12:43:23 AM (6 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/post-template.php (modified) (22 diffs)

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

@@ -314 +314 @@
     }
 
-    if ( $elements['page'] > count( $elements['pages'] ) ) { // if the requested page doesn't exist
-        $elements['page'] = count( $elements['pages'] ); // give them the highest numbered page that DOES exist
+    // If the requested page doesn't exist.
+    if ( $elements['page'] > count( $elements['pages'] ) ) {
+        // Give them the highest numbered page that DOES exist.
+        $elements['page'] = count( $elements['pages'] );
     }
 
@@ -452 +454 @@
  */
 function post_class( $class = '', $post_id = null ) {
-    // Separates classes with a single space, collates classes for post DIV
+    // Separates classes with a single space, collates classes for post DIV.
     echo 'class="' . join( ' ', get_post_class( $class, $post_id ) ) . '"';
 }
@@ -503 +505 @@
     $classes[] = 'status-' . $post->post_status;
 
-    // Post Format
+    // Post Format.
     if ( post_type_supports( $post->post_type, 'post-formats' ) ) {
         $post_format = get_post_format( $post->ID );
@@ -528 +530 @@
     }
 
-    // sticky for Sticky Posts
+    // Sticky for Sticky Posts.
     if ( is_sticky( $post->ID ) ) {
         if ( is_home() && ! is_paged() ) {
@@ -537 +539 @@
     }
 
-    // hentry for hAtom compliance
+    // hentry for hAtom compliance.
     $classes[] = 'hentry';
 
-    // All public taxonomies
+    // All public taxonomies.
     $taxonomies = get_taxonomies( array( 'public' => true ) );
     foreach ( (array) $taxonomies as $taxonomy ) {
@@ -588 +590 @@
  */
 function body_class( $class = '' ) {
-    // Separates class names with a single space, collates class names for body element
+    // Separates class names with a single space, collates class names for body element.
     echo 'class="' . join( ' ', get_body_class( $class ) ) . '"';
 }
@@ -665 +667 @@
                 $classes[] = 'postid-' . $post_id;
 
-                // Post Format
+                // Post Format.
                 if ( post_type_supports( $post->post_type, 'post-formats' ) ) {
                     $post_format = get_post_format( $post->ID );
@@ -879 +881 @@
 
 //
-// Page Template Functions for usage in Themes
+// Page Template Functions for usage in Themes.
 //
 
@@ -1124 +1126 @@
 
 //
-// Pages
+// Pages.
 //
 
@@ -1176 +1178 @@
     $pages  = get_pages( $parsed_args );
     $output = '';
-    // Back-compat with old system where both id and name were based on $name argument
+    // Back-compat with old system where both id and name were based on $name argument.
     if ( empty( $parsed_args['id'] ) ) {
         $parsed_args['id'] = $parsed_args['name'];
@@ -1277 +1279 @@
 
     if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
-        // invalid value, fall back to default.
+        // Invalid value, fall back to default.
         $parsed_args['item_spacing'] = $defaults['item_spacing'];
     }
@@ -1284 +1286 @@
     $current_page = 0;
 
-    // sanitize, mostly to keep spaces out
+    // Sanitize, mostly to keep spaces out.
     $parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] );
 
-    // Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array)
+    // Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array).
     $exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array();
 
@@ -1395 +1397 @@
 
     if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ) ) ) {
-        // invalid value, fall back to default.
+        // Invalid value, fall back to default.
         $args['item_spacing'] = $defaults['item_spacing'];
     }
@@ -1422 +1424 @@
     $list_args = $args;
 
-    // Show Home in the menu
+    // Show Home in the menu.
     if ( ! empty( $args['show_home'] ) ) {
         if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {
@@ -1434 +1436 @@
         }
         $menu .= '<li ' . $class . '><a href="' . home_url( '/' ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';
-        // If the front page is a page, add it to the exclude list
+        // If the front page is a page, add it to the exclude list.
         if ( get_option( 'show_on_front' ) == 'page' ) {
             if ( ! empty( $list_args['exclude'] ) ) {
@@ -1458 +1460 @@
     if ( $menu ) {
 
-        // wp_nav_menu doesn't set before and after
+        // wp_nav_menu() doesn't set before and after.
         if ( isset( $args['fallback_cb'] ) &&
             'wp_page_menu' === $args['fallback_cb'] &&
@@ -1500 +1502 @@
 
 //
-// Page helpers
+// Page helpers.
 //
 
@@ -1544 +1546 @@
  */
 function walk_page_dropdown_tree( ...$args ) {
-    if ( empty( $args[2]['walker'] ) ) { // the user's options are the third parameter
+    if ( empty( $args[2]['walker'] ) ) { // The user's options are the third parameter.
         $walker = new Walker_PageDropdown;
     } else {
@@ -1554 +1556 @@
 
 //
-// Attachments
+// Attachments.
 //
 
@@ -1672 +1674 @@
     } else {
         $p = '<p class="attachment">';
-        // show the medium sized image representation of the attachment if available, and link to the raw file
+        // Show the medium sized image representation of the attachment if available, and link to the raw file.
         $p .= wp_get_attachment_link( 0, 'medium', false );
         $p .= '</p>';
@@ -1692 +1694 @@
 
 //
-// Misc
+// Misc.
 //
 
@@ -1917 +1919 @@
     }
 
-    // $args array with (parent, format, right, left, type) deprecated since 3.6
+    // $args array with (parent, format, right, left, type) deprecated since 3.6.
     if ( is_array( $type ) ) {
         $type = ! empty( $type['type'] ) ? $type['type'] : $type;