Twenty Fourteen: first pass for updating code comments to reflect WP inline docs standards, see #25257.

git-svn-id: https://develop.svn.wordpress.org/trunk@25769 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-content/themes/twentyfourteen/404.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying 404 pages (Not Found).
+ * The template for displaying 404 pages (Not Found)
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/archive.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The template for displaying Archive pages.
+ * The template for displaying Archive pages
  *
  * Used to display archive-type pages if nothing more specific matches a query.
  * For example, puts together date-based pages if no date.php file exists.
@@ -10,10 +10,11 @@
  * already has tag.php for Tag archives, category.php for Category archives,
  * and author.php for Author archives.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/author.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The template for displaying Author archive pages.
+ * The template for displaying Author archive pages
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>
@@ -18,7 +19,8 @@ get_header(); ?>
 			<header class="archive-header">
 				<h1 class="archive-title">
 					<?php
-						/* Queue the first post, that way we know what author
+						/*
+						 * 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 properly
@@ -36,7 +38,8 @@ get_header(); ?>
 			</header><!-- .archive-header -->
 
 			<?php
-					/* Since we called the_post() above, we need to rewind
+					/*
+					 * Since we called the_post() above, we need to rewind
 					 * the loop back to the beginning that way we can run
 					 * the loop properly, in full.
 					 */

src/wp-content/themes/twentyfourteen/category.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The template for displaying Category pages.
+ * The template for displaying Category pages
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/comments.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The template for displaying Comments.
+ * The template for displaying Comments
  *
  * The area of the page that contains comments and the comment form.
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 /*

src/wp-content/themes/twentyfourteen/content-aside.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Aside post format.
+ * The template for displaying posts in the Aside post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-featured-post.php

@@ -1,7 +1,10 @@
 <?php
 /**
+ * The template for displaying featured posts on the front page
+ *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-gallery.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Gallery post format.
+ * The template for displaying posts in the Gallery post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 if ( has_post_thumbnail() ) :

src/wp-content/themes/twentyfourteen/content-image.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Image post format.
+ * The template for displaying posts in the Image post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-link.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Link post format.
+ * The template for displaying posts in the Link post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-none.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying a "No posts found" message.
+ * The template for displaying a "No posts found" message
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-page.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template used for displaying page content.
+ * The template used for displaying page content
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-quote.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Quote post format.
+ * The template for displaying posts in the Quote post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content-recent-formatted-post.php

@@ -1,7 +1,10 @@
 <?php
 /**
+ * The template to display recent Featured Posts
+ *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 if ( isset( $GLOBALS['content_width'] ) )
 	$GLOBALS['content_width'] = 306;

src/wp-content/themes/twentyfourteen/content-video.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying posts in the Video post format.
+ * The template for displaying posts in the Video post format
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/content.php

@@ -1,7 +1,12 @@
 <?php
 /**
+ * The default template for displaying content
+ *
+ * Used for both single and index/archive/search.
+ *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/contributor-page.php

@@ -4,6 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/featured-content.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The template for displaying featured content.
+ * The template for displaying featured content
  *
  * @todo: Add support for featured content.
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/footer.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The template for displaying the footer.
+ * The template for displaying the footer
  *
  * Contains footer content and the closing of the #main and #page div elements.
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 

src/wp-content/themes/twentyfourteen/front-page.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying the home page.
+ * The template for displaying the home page
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/full-width-page.php

@@ -4,6 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/functions.php

@@ -1,8 +1,8 @@
 <?php
 /**
- * Twenty Fourteen functions and definitions.
+ * Twenty Fourteen functions and definitions
  *
- * Sets up the theme and provides some helper functions, which are used in the
+ * Set up the theme and provides some helper functions, which are used in the
  * theme as custom template tags. Others are attached to action and filter
  * hooks in WordPress to change core functionality.
  *
@@ -17,31 +17,39 @@
  * instead attached to a filter or action hook.
  *
  * For more information on hooks, actions, and filters,
- * see http://codex.wordpress.org/Plugin_API
+ * @link http://codex.wordpress.org/Plugin_API
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 /**
- * Sets up the content width value based on the theme's design.
+ * Set up the content width value based on the theme's design.
- * @see twentyfourteen_content_width() for template-specific adjustments.
+ *
+ * @link twentyfourteen_content_width()
+ *
+ * @since Twenty Fourteen 1.0
  */
 if ( ! isset( $content_width ) )
 	$content_width = 474;
 
 if ( ! function_exists( 'twentyfourteen_setup' ) ) :
 /**
- * Sets up theme defaults and registers support for various WordPress features.
+ * Twenty Fourteen setup.
+ *
+ * Set up theme defaults and registers support for various WordPress features.
  *
  * Note that this function is hooked into the after_setup_theme hook, which
  * runs before the init hook. The init hook is too late for some features, such
  * as indicating support post thumbnails.
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_setup() {
 
 	/*
-	 * Makes Twenty Fourteen available for translation.
+	 * Make Twenty Fourteen available for translation.
 	 *
 	 * Translations can be added to the /languages/ directory.
 	 * If you're building a theme based on Twenty Fourteen, use a find and
@@ -50,18 +58,16 @@ function twentyfourteen_setup() {
 	 */
 	load_theme_textdomain( 'twentyfourteen', get_template_directory() . '/languages' );
 
-	/*
+	// This theme styles the visual editor to resemble the theme style.
-	* This theme styles the visual editor to resemble the theme style.
-	*/
 	add_editor_style( array( 'editor-style.css', twentyfourteen_font_url() ) );
 
-	// Adds RSS feed links to <head> for posts and comments.
+	// Add RSS feed links to <head> for posts and comments.
 	add_theme_support( 'automatic-feed-links' );
 
 	// Enable support for Post Thumbnails.
 	add_theme_support( 'post-thumbnails' );
 
-	// Adding several sizes for Post Thumbnails.
+	// Add several sizes for Post Thumbnails.
 	add_image_size( 'featured-thumbnail-large', 672, 0 );
 	add_image_size( 'featured-thumbnail-featured', 672, 336, true );
 	add_image_size( 'featured-thumbnail-formatted', 306, 0 );
@@ -73,7 +79,7 @@ function twentyfourteen_setup() {
 	) );
 
 	/*
-	 * Switches default core markup for search form, comment form, and comments
+	 * Switch default core markup for search form, comment form, and comments
 	 * to output valid HTML5.
 	 */
 	add_theme_support( 'html5', array(
@@ -99,7 +105,9 @@ endif; // twentyfourteen_setup
 add_action( 'after_setup_theme', 'twentyfourteen_setup' );
 
 /**
- * Adjusts content_width value for full-width and attachment templates.
+ * Adjust content_width value for full-width and attachment templates.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -111,6 +119,8 @@ add_action( 'template_redirect', 'twentyfourteen_content_width' );
 
 /**
  * Getter function for Featured Content Plugin.
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_get_featured_posts() {
 	return apply_filters( 'twentyfourteen_get_featured_posts', false );
@@ -120,6 +130,8 @@ function twentyfourteen_get_featured_posts() {
  * A helper conditional function that returns a boolean value
  * So that we can use a condition like
  * if ( twentyfourteen_has_featured_posts( 1 ) )
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_has_featured_posts( $minimum = 1 ) {
 	if ( is_paged() )
@@ -131,7 +143,9 @@ function twentyfourteen_has_featured_posts( $minimum = 1 ) {
 }
 
 /**
- * Registers two widget areas.
+ * Register two widget areas.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -172,6 +186,8 @@ add_action( 'widgets_init', 'twentyfourteen_widgets_init' );
 /**
  * Register Lato Google font for Twenty Fourteen.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @return void
  */
 function twentyfourteen_font_url() {
@@ -187,7 +203,9 @@ function twentyfourteen_font_url() {
 }
 
 /**
- * Enqueues scripts and styles for front end.
+ * Enqueue scripts and styles for front end.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -221,6 +239,8 @@ add_action( 'wp_enqueue_scripts', 'twentyfourteen_scripts' );
 /**
  * Enqueue Google fonts style to admin screen for custom header display.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @return void
  */
 function twentyfourteen_admin_fonts() {
@@ -229,7 +249,9 @@ function twentyfourteen_admin_fonts() {
 add_action( 'admin_print_scripts-appearance_page_custom-header', 'twentyfourteen_admin_fonts' );
 
 /**
- * Sets the post excerpt length to 20 words.
+ * Set the post excerpt length to 20 words.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @param int $length
  * @return int
@@ -240,7 +262,9 @@ function twentyfourteen_excerpt_length( $length ) {
 add_filter( 'excerpt_length', 'twentyfourteen_excerpt_length' );
 
 /**
- * Returns a "Continue Reading" link for excerpts
+ * Return a "Continue Reading" link for excerpts.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return string
  */
@@ -249,9 +273,11 @@ function twentyfourteen_continue_reading_link() {
 }
 
 /**
- * Replaces "[...]" (appended to automatically generated excerpts) with an
+ * Replace "[...]" (appended to automatically generated excerpts) with an
  * ellipsis and twentyeleven_continue_reading_link().
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param string $more
  * @return string
  */
@@ -261,11 +287,13 @@ function twentyfourteen_auto_excerpt_more( $more ) {
 add_filter( 'excerpt_more', 'twentyfourteen_auto_excerpt_more' );
 
 /**
- * Adds a pretty "Continue Reading" link to custom post excerpts.
+ * Add a pretty "Continue Reading" link to custom post excerpts.
  *
  * To override this link in a child theme, remove the filter and add your own
  * function tied to the get_the_excerpt filter hook.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param string $output
  * @return string
  */
@@ -279,7 +307,9 @@ add_filter( 'get_the_excerpt', 'twentyfourteen_custom_excerpt_more' );
 
 if ( ! function_exists( 'twentyfourteen_the_attached_image' ) ) :
 /**
- * Prints the attached image with a link to the next attached image.
+ * Print the attached image with a link to the next attached image.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -288,7 +318,7 @@ function twentyfourteen_the_attached_image() {
 	$attachment_size     = apply_filters( 'twentyfourteen_attachment_size', array( 1200, 1200 ) );
 	$next_attachment_url = wp_get_attachment_url();
 
-	/**
+	/*
 	 * Grab the IDs of all the image attachments in a gallery so we can get the URL
 	 * of the next adjacent image in a gallery, or the first image (if we're
 	 * looking at the last image in a gallery), or, in a gallery of one, just the
@@ -332,7 +362,9 @@ endif;
 
 if ( ! function_exists( 'twentyfourteen_list_authors' ) ) :
 /**
- * Prints a list of all site contributors who published at least one post.
+ * Print a list of all site contributors who published at least one post.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -372,8 +404,11 @@ function twentyfourteen_list_authors() {
 endif;
 
 /**
- * Gets recent formatted posts that are not featured in FC plugin.
+ * Get recent formatted posts that are not featured in FC plugin.
  *
+ * @since Twenty Fourteen 1.0
+ *
+ * @return object WP_Query
  */
 function twentyfourteen_get_recent( $post_format ) {
 	$args = array(
@@ -402,6 +437,9 @@ function twentyfourteen_get_recent( $post_format ) {
 /**
  * Filter the home page posts, and remove formatted posts visible in the sidebar from it
  *
+ * @since Twenty Fourteen 1.0
+ *
+ * @return void
  */
 function twentyfourteen_pre_get_posts( $query ) {
 	// Bail if not home, not a query, not main query.
@@ -443,7 +481,7 @@ function twentyfourteen_pre_get_posts( $query ) {
 add_action( 'pre_get_posts', 'twentyfourteen_pre_get_posts' );
 
 /**
- *  Extends the default WordPress body classes.
+ * Extend the default WordPress body classes.
  *
  * Adds body classes to denote:
  * 1. Single or multiple authors.
@@ -451,6 +489,8 @@ add_action( 'pre_get_posts', 'twentyfourteen_pre_get_posts' );
  * 3. Full-width content layout.
  * 4. Presence of footer widgets.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param array $classes A list of existing body class values.
  * @return array The filtered body class list.
  */
@@ -475,11 +515,13 @@ function twentyfourteen_body_classes( $classes ) {
 add_filter( 'body_class', 'twentyfourteen_body_classes' );
 
 /**
- * Extends the default WordPress post classes.
+ * Extend the default WordPress post classes.
  *
  * Adds a post class to denote:
  * Non-password protected page with a featured image.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param array $classes A list of existing post class values.
  * @return array The filtered post class list.
  */
@@ -492,9 +534,11 @@ function twentyfourteen_post_classes( $classes ) {
 add_filter( 'post_class', 'twentyfourteen_post_classes' );
 
 /**
- * Creates a nicely formatted and more specific title element text for output
+ * Create a nicely formatted and more specific title element text for output
  * in head of document, based on current view.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param string $title Default title text for current view.
  * @param string $sep Optional separator.
  * @return string The filtered title.
@@ -521,18 +565,11 @@ function twentyfourteen_wp_title( $title, $sep ) {
 }
 add_filter( 'wp_title', 'twentyfourteen_wp_title', 10, 2 );
 
-/**
+// Implement Custom Header features.
- * Implement the Custom Header feature
- *
- */
 require get_template_directory() . '/inc/custom-header.php';
 
-/**
+// Custom template tags for this theme.
- * Custom template tags for this theme.
- */
 require get_template_directory() . '/inc/template-tags.php';
 
-/**
+// Add Theme Customizer functionality.
- * Customizer additions
- */
 require get_template_directory() . '/inc/customizer.php';

src/wp-content/themes/twentyfourteen/header.php

@@ -1,11 +1,12 @@
 <?php
 /**
- * The Header for our theme.
+ * The Header for our theme
  *
  * Displays all of the <head> section and everything up till <div id="main">
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?><!DOCTYPE html>
 <html <?php language_attributes(); ?> class="no-js">

src/wp-content/themes/twentyfourteen/image.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying image attachments.
+ * The template for displaying image attachments
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 $metadata = wp_get_attachment_metadata();

src/wp-content/themes/twentyfourteen/inc/custom-header.php

@@ -1,11 +1,16 @@
 <?php
 /**
+ * Implement Custom Header functionality for Twenty Fourteen
+ *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 /**
- * Setup the WordPress core custom header feature.
+ * Set up the WordPress core custom header settings.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @uses twentyfourteen_header_style()
  * @uses twentyfourteen_admin_header_style()
@@ -25,9 +30,11 @@ add_action( 'after_setup_theme', 'twentyfourteen_custom_header_setup' );
 
 if ( ! function_exists( 'twentyfourteen_admin_header_style' ) ) :
 /**
- * Styles the header image displayed on the Appearance > Header admin panel.
+ * Style the header image displayed on the Appearance > Header admin panel.
  *
- * @see twentyfourteen_custom_header_setup().
+ * @link twentyfourteen_custom_header_setup().
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_admin_header_style() {
 ?>
@@ -58,9 +65,11 @@ endif; // twentyfourteen_admin_header_style
 
 if ( ! function_exists( 'twentyfourteen_admin_header_image' ) ) :
 /**
- * Custom header image markup displayed on the Appearance > Header admin panel.
+ * Create the custom header image markup displayed on the Appearance > Header admin panel.
  *
- * @see twentyfourteen_custom_header_setup().
+ * @link twentyfourteen_custom_header_setup().
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_admin_header_image() {
 ?>

src/wp-content/themes/twentyfourteen/inc/customizer.php

@@ -1,14 +1,17 @@
 <?php
 /**
- * Twenty Fourteen Theme Customizer
+ * Twenty Fourteen Theme Customizer support
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 /**
  * Add postMessage support for site title and description for the Theme Customizer.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param WP_Customize_Manager $wp_customize Theme Customizer object.
  */
 function twentyfourteen_customize_register( $wp_customize ) {
@@ -29,7 +32,9 @@ function twentyfourteen_customize_register( $wp_customize ) {
 add_action( 'customize_register', 'twentyfourteen_customize_register' );
 
 /**
- * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
+ * Bind JS handlers to make Theme Customizer preview reload changes asynchronously.
+ *
+ * @since Twenty Fourteen 1.0
  */
 function twentyfourteen_customize_preview_js() {
 	wp_enqueue_script( 'twentyfourteen_customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '20120827', true );
@@ -37,7 +42,10 @@ function twentyfourteen_customize_preview_js() {
 add_action( 'customize_preview_init', 'twentyfourteen_customize_preview_js' );
 
 /**
- * Generates two variants of the accent color, returns the original, and saves the others as theme mods.
+ * Generate two variants of the accent color, return the original, and
+ * save the others as theme mods.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @param string $color The original color.
  * @return string $color The original color, sanitized.
@@ -52,14 +60,16 @@ function twentyfourteen_generate_accent_colors( $color ) {
 }
 
 /**
- * Tweaks the brightness of a color by adjusting the RGB values by the given interval.
+ * Tweak the brightness of a color by adjusting the RGB values by the given interval.
  *
  * Use positive values of $steps to brighten the color and negative values to darken the color.
  * All three RGB values are modified by the specified steps, within the range of 0-255. The hue
  * is generally maintained unless the number of steps causes one value to be capped at 0 or 255.
  *
+ * @since Twenty Fourteen 1.0
+ *
  * @param string $color The original color, in 3- or 6-digit hexadecimal form.
- * @param int $steps The number of steps to adjust the color by, in rgb units.
+ * @param int $steps The number of steps to adjust the color by, in RGB units.
  * @return string $color The new color, in 6-digit hexadecimal form.
  */
 function twentyfourteen_adjust_color( $color, $steps ) {
@@ -86,7 +96,11 @@ function twentyfourteen_adjust_color( $color, $steps ) {
 }
 
 /**
- * Outputs the css for the Theme Customizer options.
+ * Output the CSS for the Theme Customizer options.
+ *
+ * @since Twenty Fourteen 1.0
+ *
+ * @return void
  */
 function twentyfourteen_customizer_styles() {
 	$accent_color = get_theme_mod( 'accent_color' );

src/wp-content/themes/twentyfourteen/inc/template-tags.php

@@ -1,14 +1,17 @@
 <?php
 /**
- * Custom template tags for this theme.
+ * Custom template tags for Twenty Fourteen
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 if ( ! function_exists( 'twentyfourteen_paging_nav' ) ) :
 /**
- * Displays navigation to next/previous set of posts when applicable.
+ * Display navigation to next/previous set of posts when applicable.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -58,10 +61,12 @@ endif;
 
 if ( ! function_exists( 'twentyfourteen_post_nav' ) ) :
 /**
- * Displays navigation to next/previous post when applicable.
+ * Display navigation to next/previous post when applicable.
-*
+ *
-* @return void
+ * @since Twenty Fourteen 1.0
-*/
+ *
+ * @return void
+ */
 function twentyfourteen_post_nav() {
 	// Don't print empty markup if there's nowhere to navigate.
 	$previous = ( is_attachment() ) ? get_post( get_post()->post_parent ) : get_adjacent_post( false, '', true );
@@ -86,7 +91,9 @@ endif;
 
 if ( ! function_exists( 'twentyfourteen_posted_on' ) ) :
 /**
- * Prints HTML with meta information for the current post-date/time and author.
+ * Print HTML with meta information for the current post-date/time and author.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */
@@ -105,9 +112,11 @@ function twentyfourteen_posted_on() {
 endif;
 
 /**
- * Returns true if a blog has more than 1 category
+ * Find out if blog has more than one category.
  *
- * @return boolean
+ * @since Twenty Fourteen 1.0
+ *
+ * @return boolean true if blog has more than 1 category
  */
 function twentyfourteen_categorized_blog() {
 	if ( false === ( $all_the_cool_cats = get_transient( 'all_the_cool_cats' ) ) ) {
@@ -134,6 +143,9 @@ function twentyfourteen_categorized_blog() {
 /**
  * Flush out the transients used in twentyfourteen_categorized_blog
  *
+ * @since Twenty Fourteen 1.0
+ *
+ * @return void
  */
 function twentyfourteen_category_transient_flusher() {
 	// Like, beat it. Dig?
@@ -143,7 +155,9 @@ add_action( 'edit_category', 'twentyfourteen_category_transient_flusher' );
 add_action( 'save_post',     'twentyfourteen_category_transient_flusher' );
 
 /**
- * Displays featured image with appropriate html tag.
+ * Display featured image with appropriate HTML tag.
+ *
+ * @since Twenty Fourteen 1.0
  *
  * @return void
  */

src/wp-content/themes/twentyfourteen/inc/widgets.php

@@ -1,12 +1,14 @@
 <?php
 /**
- * Makes a custom Widget for displaying Aside, Quote, Video, Image, Gallery,
+ * Custom Widget for displaying specific post formats
- * and Link posts, available with Twenty Fourteen.
  *
- * Learn more: http://codex.wordpress.org/Widgets_API#Developing_Widgets
+ * Displays posts from Aside, Quote, Video, Image, Gallery, and Link formats.
+ *
+ * @link http://codex.wordpress.org/Widgets_API#Developing_Widgets
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
@@ -14,6 +16,8 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	/**
 	 * The supported post formats.
 	 *
+	 * @since Twenty Fourteen 1.0
+	 *
 	 * @var array
 	 */
 	private $formats = array( 'aside', 'image', 'video', 'quote', 'link', 'gallery' );
@@ -21,6 +25,8 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	/**
 	 * Pluralized post format strings.
 	 *
+	 * @since Twenty Fourteen 1.0
+	 *
 	 * @var array
 	 */
 	private $format_strings;
@@ -28,6 +34,8 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	/**
 	 * Constructor.
 	 *
+	 * @since Twenty Fourteen 1.0
+	 *
 	 * @return Twenty_Fourteen_Ephemera_Widget
 	 */
 	public function __construct() {
@@ -36,7 +44,7 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 			'description' => __( 'Use this widget to list your recent Aside, Quote, Video, Image, Gallery, and Link posts', 'twentyfourteen' ),
 		) );
 
-		/**
+		/*
 		 * @todo http://core.trac.wordpress.org/ticket/23257
 		 */
 		$this->format_strings = array(
@@ -54,7 +62,9 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	}
 
 	/**
-	 * Outputs the HTML for this widget.
+	 * Output the HTML for this widget.
+	 *
+	 * @since Twenty Fourteen 1.0
 	 *
 	 * @param array $args An array of standard parameters for widgets in this theme.
 	 * @param array $instance An array of settings for this widget instance.
@@ -191,8 +201,10 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	}
 
 	/**
-	 * Deals with the settings when they are saved by the admin. Here is where
+	 * Deal with the settings when they are saved by the admin. Here is where
-	 * any validation should be dealt with.
+	 * any validation should happen.
+	 *
+	 * @since Twenty Fourteen 1.0
 	 *
 	 * @param array $new_instance
 	 * @param array $instance
@@ -210,7 +222,9 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	}
 
 	/**
-	 * Deletes the transient.
+	 * Delete the transient.
+	 *
+	 * @since Twenty Fourteen 1.0
 	 *
 	 * @return void
 	 */
@@ -219,7 +233,9 @@ class Twenty_Fourteen_Ephemera_Widget extends WP_Widget {
 	}
 
 	/**
-	 * Displays the form for this widget on the Widgets page of the Admin area.
+	 * Display the form for this widget on the Widgets page of the Admin area.
+	 *
+	 * @since Twenty Fourteen 1.0
 	 *
 	 * @param array $instance
 	 * @return void

src/wp-content/themes/twentyfourteen/index.php

@@ -1,15 +1,16 @@
 <?php
 /**
- * The main template file.
+ * The main template file
  *
  * This is the most generic template file in a WordPress theme
  * and one of the two required files for a theme (the other being style.css).
  * It is used to display a page when nothing more specific matches a query.
  * E.g., it puts together the home page when no home.php file exists.
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/page.php

@@ -1,14 +1,14 @@
 <?php
 /**
- * The template for displaying all pages.
+ * The template for displaying all pages
  *
  * This is the template that displays all pages by default.
- * Please note that this is the WordPress construct of pages
+ * Please note that this is the WordPress construct of pages and that other 'pages'
- * and that other 'pages' on your WordPress site will use a
+ * on your WordPress site will use a different template.
- * different template.
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/search.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The template for displaying Search Results pages.
+ * The template for displaying Search Results pages
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/sidebar-content.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The Content Sidebar.
+ * The Content Sidebar
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 if ( ! is_active_sidebar( 'sidebar-2' ) )
 	return;

src/wp-content/themes/twentyfourteen/sidebar-footer.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The Sidebar containing the main widget area.
+ * The Footer Sidebar
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 if ( ! is_active_sidebar( 'sidebar-3' ) )

src/wp-content/themes/twentyfourteen/sidebar.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The Sidebar containing the main widget area.
+ * The Sidebar containing the main widget area
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 ?>
 <div id="secondary">

src/wp-content/themes/twentyfourteen/single.php

@@ -1,9 +1,10 @@
 <?php
 /**
- * The Template for displaying all single posts.
+ * The Template for displaying all single posts
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/tag.php

@@ -1,13 +1,14 @@
 <?php
 /**
- * The template for displaying Tag pages.
+ * The template for displaying Tag pages
  *
  * Used to display archive-type pages for posts in a tag.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>

src/wp-content/themes/twentyfourteen/taxonomy-post_format.php

@@ -1,15 +1,16 @@
 <?php
 /**
- * The template for displaying Post Format pages.
+ * The template for displaying Post Format pages
  *
  * Used to display archive-type pages for posts with a post format.
  * If you'd like to further customize these Post Format views, you may create a
  * new template file for each specific one.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Fourteen
+ * @since Twenty Fourteen 1.0
  */
 
 get_header(); ?>