Changeset 47122 for trunk/src/wp-includes/general-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/general-template.php (modified) (25 diffs)

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

@@ -704 +704 @@
 function get_bloginfo( $show = '', $filter = 'raw' ) {
     switch ( $show ) {
-        case 'home': // DEPRECATED
-        case 'siteurl': // DEPRECATED
+        case 'home':    // Deprecated.
+        case 'siteurl': // Deprecated.
             _deprecated_argument(
                 __FUNCTION__,
@@ -1072 +1072 @@
 
         /*
-        * If we're on the blog page that is not the homepage or
-        * a single post of any post type, use the post title.
+        * If we're on the blog page that is not the homepage
+        * or a single post of any post type, use the post title.
         */
     } elseif ( is_home() || is_singular() ) {
@@ -1196 +1196 @@
     $title    = '';
 
-    $t_sep = '%WP_TITLE_SEP%'; // Temporary separator, for accurate flipping, if necessary
-
-    // If there is a post
+    $t_sep = '%WP_TITLE_SEP%'; // Temporary separator, for accurate flipping, if necessary.
+
+    // If there is a post.
     if ( is_single() || ( is_home() && ! is_front_page() ) || ( is_page() && ! is_front_page() ) ) {
         $title = single_post_title( '', false );
     }
 
-    // If there's a post type archive
+    // If there's a post type archive.
     if ( is_post_type_archive() ) {
         $post_type = get_query_var( 'post_type' );
@@ -1215 +1215 @@
     }
 
-    // If there's a category or tag
+    // If there's a category or tag.
     if ( is_category() || is_tag() ) {
         $title = single_term_title( '', false );
     }
 
-    // If there's a taxonomy
+    // If there's a taxonomy.
     if ( is_tax() ) {
         $term = get_queried_object();
@@ -1229 +1229 @@
     }
 
-    // If there's an author
+    // If there's an author.
     if ( is_author() && ! is_post_type_archive() ) {
         $author = get_queried_object();
@@ -1242 +1242 @@
     }
 
-    // If there's a month
+    // If there's a month.
     if ( is_archive() && ! empty( $m ) ) {
         $my_year  = substr( $m, 0, 4 );
@@ -1250 +1250 @@
     }
 
-    // If there's a year
+    // If there's a year.
     if ( is_archive() && ! empty( $year ) ) {
         $title = $year;
@@ -1261 +1261 @@
     }
 
-    // If it's a search
+    // If it's a search.
     if ( is_search() ) {
         /* translators: 1: Separator, 2: Search query. */
@@ -1267 +1267 @@
     }
 
-    // If it's a 404 page
+    // If it's a 404 page.
     if ( is_404() ) {
         $title = __( 'Page not found' );
@@ -1286 +1286 @@
     $title_array = apply_filters( 'wp_title_parts', explode( $t_sep, $title ) );
 
-    // Determines position of the separator and direction of the breadcrumb
-    if ( 'right' == $seplocation ) { // sep on right, so reverse the order
+    // Determines position of the separator and direction of the breadcrumb.
+    if ( 'right' == $seplocation ) { // Separator on right, so reverse the order.
         $title_array = array_reverse( $title_array );
         $title       = implode( " $sep ", $title_array ) . $prefix;
@@ -1305 +1305 @@
     $title = apply_filters( 'wp_title', $title, $sep, $seplocation );
 
-    // Send it out
+    // Send it out.
     if ( $display ) {
         echo $title;
@@ -1748 +1748 @@
     } elseif ( 'html' === $format ) {
         $link_html = "\t<li>$before<a href='$url'$aria_current>$text</a>$after</li>\n";
-    } else { // custom
+    } else { // Custom.
         $link_html = "\t$before<a href='$url'$aria_current>$text</a>$after\n";
     }
@@ -1851 +1851 @@
     }
 
-    // this is what will separate dates on weekly archive links
+    // This is what will separate dates on weekly archive links.
     $archive_week_separator = '&#8211;';
 
@@ -2096 +2096 @@
         $w = (int) $_GET['w'];
     }
-    // week_begins = 0 stands for Sunday
+    // week_begins = 0 stands for Sunday.
     $week_begins = (int) get_option( 'start_of_week' );
 
-    // Let's figure out when we are
+    // Let's figure out when we are.
     if ( ! empty( $monthnum ) && ! empty( $year ) ) {
         $thismonth = zeroise( intval( $monthnum ), 2 );
         $thisyear  = (int) $year;
     } elseif ( ! empty( $w ) ) {
-        // We need to get the month from MySQL
+        // We need to get the month from MySQL.
         $thisyear = (int) substr( $m, 0, 4 );
-        //it seems MySQL's weeks disagree with PHP's
+        // It seems MySQL's weeks disagree with PHP's.
         $d         = ( ( $w - 1 ) * 7 ) + 6;
         $thismonth = $wpdb->get_var( "SELECT DATE_FORMAT((DATE_ADD('{$thisyear}0101', INTERVAL $d DAY) ), '%m')" );
@@ -2124 +2124 @@
     $last_day  = gmdate( 't', $unixmonth );
 
-    // Get the next and previous month and year with at least one post
+    // Get the next and previous month and year with at least one post.
     $previous = $wpdb->get_row(
         "SELECT MONTH(post_date) AS month, YEAR(post_date) AS year
@@ -2199 +2199 @@
     $daywithpost = array();
 
-    // Get days with posts
+    // Get days with posts.
     $dayswithposts = $wpdb->get_results(
         "SELECT DISTINCT DAYOFMONTH(post_date)
@@ -2213 +2213 @@
     }
 
-    // See how much we should pad in the beginning
+    // See how much we should pad in the beginning.
     $pad = calendar_week_mod( gmdate( 'w', $unixmonth ) - $week_begins );
     if ( 0 != $pad ) {
@@ -2237 +2237 @@
 
         if ( in_array( $day, $daywithpost ) ) {
-            // any posts today?
+            // Any posts today?
             $date_format = gmdate( _x( 'F j, Y', 'daily archives date format' ), strtotime( "{$thisyear}-{$thismonth}-{$day}" ) );
             /* translators: Post calendar label. %s: Date. */
@@ -3340 +3340 @@
         $wp_rich_edit = false;
 
-        if ( get_user_option( 'rich_editing' ) == 'true' || ! is_user_logged_in() ) { // default to 'true' for logged out users
+        if ( get_user_option( 'rich_editing' ) == 'true' || ! is_user_logged_in() ) { // Default to 'true' for logged out users.
             if ( $is_safari ) {
                 $wp_rich_edit = ! wp_is_mobile() || ( preg_match( '!AppleWebKit/(\d+)!', $_SERVER['HTTP_USER_AGENT'], $match ) && intval( $match[1] ) >= 534 );
@@ -3372 +3372 @@
  */
 function wp_default_editor() {
-    $r = user_can_richedit() ? 'tinymce' : 'html'; // defaults
-    if ( wp_get_current_user() ) { // look for cookie
+    $r = user_can_richedit() ? 'tinymce' : 'html'; // Defaults.
+    if ( wp_get_current_user() ) { // Look for cookie.
         $ed = get_user_setting( 'editor', 'tinymce' );
         $r  = ( in_array( $ed, array( 'tinymce', 'html', 'test' ) ) ) ? $ed : $r;
@@ -4095 +4095 @@
 
     $defaults = array(
-        'base'               => $pagenum_link, // http://example.com/all_posts.php%_% : %_% is replaced by format (below)
-        'format'             => $format, // ?page=%#% : %#% is replaced by the page number
+        'base'               => $pagenum_link, // http://example.com/all_posts.php%_% : %_% is replaced by format (below).
+        'format'             => $format, // ?page=%#% : %#% is replaced by the page number.
         'total'              => $total,
         'current'            => $current,
@@ -4107 +4107 @@
         'mid_size'           => 2,
         'type'               => 'plain',
-        'add_args'           => array(), // array of query args to add
+        'add_args'           => array(), // Array of query args to add.
         'add_fragment'       => '',
         'before_page_number' => '',
@@ -4137 +4137 @@
     }
 
-    // Who knows what else people pass in $args
+    // Who knows what else people pass in $args.
     $total = (int) $args['total'];
     if ( $total < 2 ) {
@@ -4143 +4143 @@
     }
     $current  = (int) $args['current'];
-    $end_size = (int) $args['end_size']; // Out of bounds?  Make it the default.
+    $end_size = (int) $args['end_size']; // Out of bounds? Make it the default.
     if ( $end_size < 1 ) {
         $end_size = 1;
@@ -4314 +4314 @@
     );
 
-    // Other color schemes are not available when running out of src
+    // Other color schemes are not available when running out of src.
     if ( false !== strpos( get_bloginfo( 'version' ), '-src' ) ) {
         return;