Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.
Built from https://develop.svn.wordpress.org/trunk@47122


git-svn-id: http://core.svn.wordpress.org/trunk@46922 1a063a9b-81f0-0310-95a4-ce76da25c4cd

archive.php

@@ -43,12 +43,13 @@ get_header(); ?>
 			</header><!-- .archive-header -->
 
 			<?php
-			/* Start the Loop */
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 
-				/* Include the post format-specific template for the content. If you want to
+				/*
-				 * this in a child theme then include a file called content-___.php
+				 * Include the post format-specific template for the content. If you want
+				 * to use this in a child theme then include a file called content-___.php
 				 * (where ___ is the post format) and that will be used instead.
 				 */
 				get_template_part( 'content', get_post_format() );

author.php

@@ -19,7 +19,8 @@ get_header(); ?>
 		<?php if ( have_posts() ) : ?>
 
 			<?php
-				/* Queue the first post, that way we know
+				/*
+				 * Queue the first post, that way we know
 				 * what author we're dealing with (if that is the case).
 				 *
 				 * We reset this later so we can run the loop
@@ -38,9 +39,10 @@ get_header(); ?>
 			</header><!-- .archive-header -->
 
 			<?php
-				/* Since we called the_post() above, we need to
+				/*
-				 * rewind the loop back to the beginning that way
+				 * Since we called the_post() above, we need
-				 * we can run the loop properly, in full.
+				 * to rewind the loop back to the beginning.
+				 * That way we can run the loop properly, in full.
 				 */
 				rewind_posts();
 			?>
@@ -77,8 +79,8 @@ get_header(); ?>
 			</div><!-- .author-info -->
 			<?php endif; ?>
 
-			<?php /* Start the Loop */ ?>
 			<?php
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 				?>

category.php

@@ -25,18 +25,19 @@ get_header(); ?>
 				?>
 				</h1>
 
-			<?php if ( category_description() ) : // Show an optional category description ?>
+			<?php if ( category_description() ) : // Show an optional category description. ?>
 				<div class="archive-meta"><?php echo category_description(); ?></div>
 			<?php endif; ?>
 			</header><!-- .archive-header -->
 
 			<?php
-			/* Start the Loop */
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 
-				/* Include the post format-specific template for the content. If you want to
+				/*
-				 * this in a child theme then include a file called content-___.php
+				 * Include the post format-specific template for the content. If you want
+				 * to use this in a child theme then include a file called content-___.php
 				 * (where ___ is the post format) and that will be used instead.
 				 */
 				get_template_part( 'content', get_post_format() );

comments.php

@@ -57,16 +57,17 @@ if ( post_password_required() ) {
 			?>
 		</ol><!-- .commentlist -->
 
-		<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through ?>
+		<?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // Are there comments to navigate through? ?>
 		<nav id="comment-nav-below" class="navigation" role="navigation">
 			<h1 class="assistive-text section-heading"><?php _e( 'Comment navigation', 'twentytwelve' ); ?></h1>
 			<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentytwelve' ) ); ?></div>
 			<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentytwelve' ) ); ?></div>
 		</nav>
-		<?php endif; // check for comment navigation ?>
+		<?php endif; // Check for comment navigation. ?>
 
 		<?php
-		/* If there are no comments and comments are closed, let's leave a note.
+		/*
+		 * If there are no comments and comments are closed, let's leave a note.
 		 * But we only want the note on posts and pages that had comments in the first place.
 		 */
 		if ( ! comments_open() && get_comments_number() ) :

content.php

@@ -37,7 +37,7 @@
 			<?php endif; // comments_open() ?>
 		</header><!-- .entry-header -->
 
-		<?php if ( is_search() ) : // Only display Excerpts for Search ?>
+		<?php if ( is_search() ) : // Only display excerpts for search. ?>
 		<div class="entry-summary">
 			<?php the_excerpt(); ?>
 		</div><!-- .entry-summary -->
@@ -58,7 +58,10 @@
 		<footer class="entry-meta">
 			<?php twentytwelve_entry_meta(); ?>
 			<?php edit_post_link( __( 'Edit', 'twentytwelve' ), '<span class="edit-link">', '</span>' ); ?>
-			<?php if ( is_singular() && get_the_author_meta( 'description' ) && is_multi_author() ) : // If a user has filled out their description and this is a multi-author blog, show a bio on their entries. ?>
+			<?php
+			// If a user has filled out their description and this is a multi-author blog, show a bio on their entries.
+			if ( is_singular() && get_the_author_meta( 'description' ) && is_multi_author() ) :
+				?>
 				<div class="author-info">
 					<div class="author-avatar">
 						<?php
@@ -77,10 +80,10 @@
 						<p><?php the_author_meta( 'description' ); ?></p>
 						<div class="author-link">
 							<a href="<?php echo esc_url( get_author_posts_url( get_the_author_meta( 'ID' ) ) ); ?>" rel="author">
-								<?php
+							<?php
-								/* translators: %s: Author display name. */
+							/* translators: %s: Author display name. */
-								printf( __( 'View all posts by %s <span class="meta-nav">&rarr;</span>', 'twentytwelve' ), get_the_author() );
+							printf( __( 'View all posts by %s <span class="meta-nav">&rarr;</span>', 'twentytwelve' ), get_the_author() );
-								?>
+							?>
 							</a>
 						</div><!-- .author-link	-->
 					</div><!-- .author-description -->

functions.php

@@ -120,7 +120,7 @@ function twentytwelve_setup() {
 
 	// This theme uses a custom image size for featured images, displayed on "standard" posts.
 	add_theme_support( 'post-thumbnails' );
-	set_post_thumbnail_size( 624, 9999 ); // Unlimited height, soft crop
+	set_post_thumbnail_size( 624, 9999 ); // Unlimited height, soft crop.
 
 	// Indicate widget sidebars can use selective refresh in the Customizer.
 	add_theme_support( 'customize-selective-refresh-widgets' );
@@ -482,7 +482,7 @@ if ( ! function_exists( 'twentytwelve_comment' ) ) :
 			</article><!-- #comment-## -->
 				<?php
 				break;
-		endswitch; // end comment_type check
+		endswitch; // End comment_type check.
 	}
 endif;
 
@@ -706,7 +706,7 @@ if ( ! function_exists( 'wp_body_open' ) ) :
 	/**
 	 * Fire the wp_body_open action.
 	 *
-	 * Added for backwards compatibility to support pre 5.2.0 WordPress versions.
+	 * Added for backward compatibility to support pre-5.2.0 WordPress versions.
 	 *
 	 * @since Twenty Twelve 3.0
 	 */

image.php

@@ -73,38 +73,38 @@ get_header(); ?>
 				if ( $attachment->ID == $post->ID ) {
 					break;
 				}
-endforeach;
+			endforeach;
 
-			// If there is more than 1 attachment in a gallery
+			// If there is more than 1 attachment in a gallery...
 			if ( count( $attachments ) > 1 ) :
 				$k++;
 				if ( isset( $attachments[ $k ] ) ) :
-					// get the URL of the next image attachment
+					// ...get the URL of the next image attachment.
 					$next_attachment_url = get_attachment_link( $attachments[ $k ]->ID );
 				else :
-					// or get the URL of the first image attachment
+					// ...or get the URL of the first image attachment.
 					$next_attachment_url = get_attachment_link( $attachments[0]->ID );
 				endif;
-else :
+			else :
-	// or, if there's only 1 image, get the URL of the image
+				// Or, if there's only 1 image, get the URL of the image.
-	$next_attachment_url = wp_get_attachment_url();
+				$next_attachment_url = wp_get_attachment_url();
-endif;
+			endif;
-?>
+			?>
 								<a href="<?php echo esc_url( $next_attachment_url ); ?>" title="<?php the_title_attribute(); ?>" rel="attachment">
-													<?php
+									<?php
-													/**
+									/**
-													 * Filter the image attachment size to use.
+									 * Filter the image attachment size to use.
-													 *
+									 *
-													 * @since Twenty Twelve 1.0
+									 * @since Twenty Twelve 1.0
-													 *
+									 *
-													 * @param array $size {
+									 * @param array $size {
-													 *     @type int The attachment height in pixels.
+									 *     @type int The attachment height in pixels.
-													 *     @type int The attachment width in pixels.
+									 *     @type int The attachment width in pixels.
-													 * }
+									 * }
-													 */
+									 */
-													$attachment_size = apply_filters( 'twentytwelve_attachment_size', array( 960, 960 ) );
+									$attachment_size = apply_filters( 'twentytwelve_attachment_size', array( 960, 960 ) );
-													echo wp_get_attachment_image( $post->ID, $attachment_size );
+									echo wp_get_attachment_image( $post->ID, $attachment_size );
-													?>
+									?>
 								</a>
 
 								<?php if ( ! empty( $post->post_excerpt ) ) : ?>
@@ -134,7 +134,7 @@ endif;
 
 				<?php comments_template(); ?>
 
-			<?php endwhile; // end of the loop. ?>
+			<?php endwhile; // End of the loop. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

inc/custom-header.php

@@ -70,7 +70,7 @@ add_action( 'admin_print_styles-appearance_page_custom-header', 'twentytwelve_cu
 function twentytwelve_header_style() {
 	$text_color = get_header_textcolor();
 
-	// If no custom options for text are set, let's bail
+	// If no custom options for text are set, let's bail.
 	if ( $text_color == get_theme_support( 'custom-header', 'default-text-color' ) ) {
 		return;
 	}

index.php

@@ -20,8 +20,8 @@ get_header(); ?>
 		<div id="content" role="main">
 		<?php if ( have_posts() ) : ?>
 
-			<?php /* Start the Loop */ ?>
 			<?php
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 				?>
@@ -63,11 +63,11 @@ get_header(); ?>
 					<p><?php _e( 'Apologies, but no results were found. Perhaps searching will help find a related post.', 'twentytwelve' ); ?></p>
 					<?php get_search_form(); ?>
 				</div><!-- .entry-content -->
-			<?php endif; // end current_user_can() check ?>
+			<?php endif; // End current_user_can() check. ?>
 
 			</article><!-- #post-0 -->
 
-		<?php endif; // end have_posts() check ?>
+		<?php endif; // End have_posts() check. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

js/theme-customizer.js

@@ -18,7 +18,7 @@
 		} );
 	} );
 
-	// Header text color
+	// Header text color.
 	wp.customize( 'header_textcolor', function( value ) {
 		value.bind( function( to ) {
 			if ( 'blank' === to ) {

page-templates/front-page.php

@@ -29,7 +29,7 @@ get_header(); ?>
 
 				<?php get_template_part( 'content', 'page' ); ?>
 
-			<?php endwhile; // end of the loop. ?>
+			<?php endwhile; // End of the loop. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

page-templates/full-width.php

@@ -25,7 +25,7 @@ get_header(); ?>
 				?>
 				<?php get_template_part( 'content', 'page' ); ?>
 				<?php comments_template( '', true ); ?>
-			<?php endwhile; // end of the loop. ?>
+			<?php endwhile; // End of the loop. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

page.php

@@ -23,7 +23,7 @@ get_header(); ?>
 				?>
 				<?php get_template_part( 'content', 'page' ); ?>
 				<?php comments_template( '', true ); ?>
-			<?php endwhile; // end of the loop. ?>
+			<?php endwhile; // End of the loop. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

search.php

@@ -25,8 +25,8 @@ get_header(); ?>
 
 			<?php twentytwelve_content_nav( 'nav-above' ); ?>
 
-			<?php /* Start the Loop */ ?>
 			<?php
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 				?>

single.php

@@ -27,7 +27,7 @@ get_header(); ?>
 
 				<?php comments_template( '', true ); ?>
 
-			<?php endwhile; // end of the loop. ?>
+			<?php endwhile; // End of the loop. ?>
 
 		</div><!-- #content -->
 	</div><!-- #primary -->

tag.php

@@ -25,19 +25,19 @@ get_header(); ?>
 				?>
 				</h1>
 
-			<?php if ( tag_description() ) : // Show an optional tag description ?>
+			<?php if ( tag_description() ) : // Show an optional tag description. ?>
 				<div class="archive-meta"><?php echo tag_description(); ?></div>
 			<?php endif; ?>
 			</header><!-- .archive-header -->
 
 			<?php
-			/* Start the Loop */
+			// Start the Loop.
 			while ( have_posts() ) :
 				the_post();
 
 				/*
-				 * Include the post format-specific template for the content. If you want to
+				 * Include the post format-specific template for the content. If you want
-				 * this in a child theme then include a file called content-___.php
+				 * to use this in a child theme then include a file called content-___.php
 				 * (where ___ is the post format) and that will be used instead.
 				 */
 				get_template_part( 'content', get_post_format() );