Twenty Twelve: update code comments to reflect WP inline docs standards. Props DrewAPicture, see #25256.

Built from https://develop.svn.wordpress.org/trunk@25521


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

404.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The template for displaying 404 pages (Not Found).
+ * The template for displaying 404 pages (Not Found)
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

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,7 +10,7 @@
  * 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_Twelve

author.php

@@ -1,10 +1,10 @@
 <?php
 /**
- * The template for displaying Author Archive pages.
+ * The template for displaying Author Archive pages
  *
  * Used to display archive-type pages for posts by an author.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Twelve
@@ -47,7 +47,11 @@ get_header(); ?>
 			if ( get_the_author_meta( 'description' ) ) : ?>
 			<div class="author-info">
 				<div class="author-avatar">
-					<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentytwelve_author_bio_avatar_size', 60 ) ); ?>
+					<?php
+					//duplicate_hook
+					$author_bio_avatar_size = apply_filters( 'twentytwelve_author_bio_avatar_size', 68 );
+					echo get_avatar( get_the_author_meta( 'user_email' ), $author_bio_avatar_size );
+					?>
 				</div><!-- .author-avatar -->
 				<div class="author-description">
 					<h2><?php printf( __( 'About %s', 'twentytwelve' ), get_the_author() ); ?></h2>

category.php

@@ -1,10 +1,10 @@
 <?php
 /**
- * The template for displaying Category pages.
+ * The template for displaying Category pages
  *
  * Used to display archive-type pages for posts in a category.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

comments.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The template for displaying Comments.
+ * The template for displaying Comments
  *
  * The area of the page that contains both current comments
  * and the comment form. The actual display of comments is
@@ -12,7 +12,7 @@
  * @since Twenty Twelve 1.0
  */
 
-/*
+/**
  * If the current post is protected by a password and
  * the visitor has not yet entered the password we will
  * return early without loading the comments.

content-none.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The template for displaying a "No posts found" message.
+ * The template for displaying a "No posts found" message
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

content-status.php

@@ -14,7 +14,17 @@
 				<h1><?php the_author(); ?></h1>
 				<h2><a href="<?php the_permalink(); ?>" title="<?php echo esc_attr( sprintf( __( 'Permalink to %s', 'twentytwelve' ), the_title_attribute( 'echo=0' ) ) ); ?>" rel="bookmark"><?php echo get_the_date(); ?></a></h2>
 			</header>
-			<?php echo get_avatar( get_the_author_meta( 'ID' ), apply_filters( 'twentytwelve_status_avatar', '48' ) ); ?>
+			<?php
+			/**
+			 * Filter the status avatar size.
+			 *
+			 * @since Twenty Twelve 1.0
+			 *
+			 * @param int $size The height and width of the avatar in pixels.
+			 */
+			$status_avatar = apply_filters( 'twentytwelve_status_avatar', 48 );
+			echo get_avatar( get_the_author_meta( 'ID' ), $status_avatar );
+			?>
 		</div><!-- .entry-header -->
 
 		<div class="entry-content">

content.php

@@ -1,6 +1,8 @@
 <?php
 /**
- * The default template for displaying content. Used for both single and index/archive/search.
+ * The default template for displaying content
+ *
+ * Used for both single and index/archive/search.
  *
  * @package WordPress
  * @subpackage Twenty_Twelve
@@ -47,7 +49,17 @@
 			<?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. ?>
 				<div class="author-info">
 					<div class="author-avatar">
-						<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentytwelve_author_bio_avatar_size', 68 ) ); ?>
+						<?php
+						/**
+						 * Filter the author bio avatar size.
+						 *
+						 * @since Twenty Twelve 1.0
+						 *
+						 * @param int $size The height and width of the avatar in pixels.
+						 */
+						$author_bio_avatar_size = apply_filters( 'twentytwelve_author_bio_avatar_size', 68 );
+						echo get_avatar( get_the_author_meta( 'user_email' ), $author_bio_avatar_size );
+						?>
 					</div><!-- .author-avatar -->
 					<div class="author-description">
 						<h2><?php printf( __( 'About %s', 'twentytwelve' ), get_the_author() ); ?></h2>

footer.php

@@ -1,9 +1,8 @@
 <?php
 /**
- * The template for displaying the footer.
+ * The template for displaying the footer
  *
- * Contains footer content and the closing of the
+ * Contains footer content and the closing of the #main and #page div elements.
- * #main and #page div elements.
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

functions.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Twenty Twelve functions and definitions.
+ * Twenty Twelve functions and definitions
  *
  * Sets up the theme and provides some helper functions, which are used
  * in the theme as custom template tags. Others are attached to action and
@@ -15,7 +15,7 @@
  * Functions that are not pluggable (not wrapped in function_exists()) are instead attached
  * to a filter or action hook.
  *
- * For more information on hooks, actions, and filters, see http://codex.wordpress.org/Plugin_API.
+ * For more information on hooks, actions, and filters, @link http://codex.wordpress.org/Plugin_API
  *
  * @package WordPress
  * @subpackage Twenty_Twelve
@@ -23,12 +23,14 @@
  */
 
 /**
- * Sets up the content width value based on the theme's design and stylesheet.
+ * Set up the content width value based on the theme's design and stylesheet.
  */
 if ( ! isset( $content_width ) )
 	$content_width = 625;
 
 /**
+ * Twenty Twelve setup.
+ *
  * Sets up theme defaults and registers the various WordPress features that
  * Twenty Twelve supports.
  *
@@ -42,7 +44,7 @@ if ( ! isset( $content_width ) )
  * @since Twenty Twelve 1.0
  */
 function twentytwelve_setup() {
-	/*
+	/**
 	 * Makes Twenty Twelve available for translation.
 	 *
 	 * Translations can be added to the /languages/ directory.
@@ -63,9 +65,9 @@ function twentytwelve_setup() {
 	// This theme uses wp_nav_menu() in one location.
 	register_nav_menu( 'primary', __( 'Primary Menu', 'twentytwelve' ) );
 
-	/*
+	/**
-	 * This theme supports custom background color and image, and here
+	 * This theme supports custom background color and image,
-	 * we also set up the default background color.
+	 * and here we also set up the default background color.
 	 */
 	add_theme_support( 'custom-background', array(
 		'default-color' => 'e6e6e6',
@@ -78,12 +80,12 @@ function twentytwelve_setup() {
 add_action( 'after_setup_theme', 'twentytwelve_setup' );
 
 /**
- * Adds support for a custom header image.
+ * Add support for a custom header image.
  */
 require( get_template_directory() . '/inc/custom-header.php' );
 
 /**
- * Returns the Google font stylesheet URL if available.
+ * Return the Google font stylesheet URL if available.
  *
  * The use of Open Sans by default is localized. For languages that use
  * characters not supported by the font, the font can be disabled.
@@ -95,13 +97,17 @@ require( get_template_directory() . '/inc/custom-header.php' );
 function twentytwelve_get_font_url() {
 	$font_url = '';
 
-	/* translators: If there are characters in your language that are not supported
+	/**
-	 by Open Sans, translate this to 'off'. Do not translate into your own language. */
+	 * translators: If there are characters in your language that are not supported
+	 * by Open Sans, translate this to 'off'. Do not translate into your own language.
+	 */
 	if ( 'off' !== _x( 'on', 'Open Sans font: on or off', 'twentytwelve' ) ) {
 		$subsets = 'latin,latin-ext';
 
-		/* translators: To add an additional Open Sans character subset specific to your language, translate
+		/**
-		 this to 'greek', 'cyrillic' or 'vietnamese'. Do not translate into your own language. */
+		 * translators: To add an additional Open Sans character subset specific to your language,
+		 * translate this to 'greek', 'cyrillic' or 'vietnamese'. Do not translate into your own language.
+		 */
 		$subset = _x( 'no-subset', 'Open Sans font: add new subset (greek, cyrillic, vietnamese)', 'twentytwelve' );
 
 		if ( 'cyrillic' == $subset )
@@ -123,21 +129,23 @@ function twentytwelve_get_font_url() {
 }
 
 /**
- * Enqueues scripts and styles for front-end.
+ * Enqueue scripts and styles for front-end.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @return void
  */
 function twentytwelve_scripts_styles() {
 	global $wp_styles;
 
-	/*
+	/**
 	 * Adds JavaScript to pages with the comment form to support
 	 * sites with threaded comments (when in use).
 	 */
 	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) )
 		wp_enqueue_script( 'comment-reply' );
 
-	/*
+	/**
 	 * Adds JavaScript for handling the navigation menu hide-and-show behavior.
 	 */
 	wp_enqueue_script( 'twentytwelve-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '1.0', true );
@@ -146,12 +154,12 @@ function twentytwelve_scripts_styles() {
 	if ( ! empty( $font_url ) )
 		wp_enqueue_style( 'twentytwelve-fonts', esc_url_raw( $font_url ), array(), null );
 
-	/*
+	/**
 	 * Loads our main stylesheet.
 	 */
 	wp_enqueue_style( 'twentytwelve-style', get_stylesheet_uri() );
 
-	/*
+	/**
 	 * Loads the Internet Explorer specific stylesheet.
 	 */
 	wp_enqueue_style( 'twentytwelve-ie', get_template_directory_uri() . '/css/ie.css', array( 'twentytwelve-style' ), '20121010' );
@@ -160,6 +168,8 @@ function twentytwelve_scripts_styles() {
 add_action( 'wp_enqueue_scripts', 'twentytwelve_scripts_styles' );
 
 /**
+ * Filter TinyMCE CSS path to include Google Fonts.
+ *
  * Adds additional stylesheets to the TinyMCE editor if needed.
  *
  * @uses twentytwelve_get_font_url() To get the Google Font stylesheet URL.
@@ -167,7 +177,7 @@ add_action( 'wp_enqueue_scripts', 'twentytwelve_scripts_styles' );
  * @since Twenty Twelve 1.2
  *
  * @param string $mce_css CSS path to load in TinyMCE.
- * @return string
+ * @return string Filtered CSS path.
  */
 function twentytwelve_mce_css( $mce_css ) {
 	$font_url = twentytwelve_get_font_url();
@@ -185,6 +195,8 @@ function twentytwelve_mce_css( $mce_css ) {
 add_filter( 'mce_css', 'twentytwelve_mce_css' );
 
 /**
+ * Filter the page title.
+ *
  * Creates a nicely formatted and more specific title element text
  * for output in head of document, based on current view.
  *
@@ -217,6 +229,8 @@ function twentytwelve_wp_title( $title, $sep ) {
 add_filter( 'wp_title', 'twentytwelve_wp_title', 10, 2 );
 
 /**
+ * Filter the page menu arguments.
+ *
  * Makes our wp_nav_menu() fallback -- wp_page_menu() -- show a home link.
  *
  * @since Twenty Twelve 1.0
@@ -229,6 +243,8 @@ function twentytwelve_page_menu_args( $args ) {
 add_filter( 'wp_page_menu_args', 'twentytwelve_page_menu_args' );
 
 /**
+ * Register sidebars.
+ *
  * Registers our main widget area and the front page widget areas.
  *
  * @since Twenty Twelve 1.0
@@ -297,6 +313,8 @@ if ( ! function_exists( 'twentytwelve_comment' ) ) :
  * Used as a callback by wp_list_comments() for displaying the comments.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @return void
  */
 function twentytwelve_comment( $comment, $args, $depth ) {
 	$GLOBALS['comment'] = $comment;
@@ -353,11 +371,15 @@ endif;
 
 if ( ! function_exists( 'twentytwelve_entry_meta' ) ) :
 /**
+ * Set up post entry meta.
+ *
  * Prints HTML with meta information for current post: categories, tags, permalink, author, and date.
  *
  * Create your own twentytwelve_entry_meta() to override in a child theme.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @return void
  */
 function twentytwelve_entry_meta() {
 	// Translators: used between list items, there is a space after the comma.
@@ -399,6 +421,8 @@ function twentytwelve_entry_meta() {
 endif;
 
 /**
+ * Extend the default WordPress body classes.
+ *
  * Extends the default WordPress body class to denote:
  * 1. Using a full-width layout, when no active widgets in the sidebar
  *    or full-width template.
@@ -410,7 +434,7 @@ endif;
  *
  * @since Twenty Twelve 1.0
  *
- * @param array Existing class values.
+ * @param array $classes Existing class values.
  * @return array Filtered class values.
  */
 function twentytwelve_body_class( $classes ) {
@@ -447,10 +471,14 @@ function twentytwelve_body_class( $classes ) {
 add_filter( 'body_class', 'twentytwelve_body_class' );
 
 /**
+ * Adjust content width in certain contexts.
+ *
  * Adjusts content_width value for full-width and single image attachment
  * templates, and when there are no active widgets in the sidebar.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @return void
  */
 function twentytwelve_content_width() {
 	if ( is_page_template( 'page-templates/full-width.php' ) || is_attachment() || ! is_active_sidebar( 'sidebar-1' ) ) {
@@ -461,11 +489,13 @@ function twentytwelve_content_width() {
 add_action( 'template_redirect', 'twentytwelve_content_width' );
 
 /**
- * Add postMessage support for site title and description for the Theme Customizer.
+ * Register postMessage support.
+ *
+ * Add postMessage support for site title and description for the Customizer.
  *
  * @since Twenty Twelve 1.0
  *
- * @param WP_Customize_Manager $wp_customize Theme Customizer object.
+ * @param WP_Customize_Manager $wp_customize Customizer object.
  * @return void
  */
 function twentytwelve_customize_register( $wp_customize ) {
@@ -476,9 +506,13 @@ function twentytwelve_customize_register( $wp_customize ) {
 add_action( 'customize_register', 'twentytwelve_customize_register' );
 
 /**
- * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
+ * Enqueue Javascript postMessage handlers for the Customizer.
+ *
+ * Binds JS handlers to make the Customizer preview reload changes asynchronously.
  *
  * @since Twenty Twelve 1.0
+ *
+ * @return void
  */
 function twentytwelve_customize_preview_js() {
 	wp_enqueue_script( 'twentytwelve-customizer', get_template_directory_uri() . '/js/theme-customizer.js', array( 'customize-preview' ), '20130301', true );

header.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The Header for our theme.
+ * The Header template for our theme
  *
  * Displays all of the <head> section and everything up till <div id="main">
  *

image.php

@@ -1,8 +1,8 @@
 <?php
 /**
- * The template for displaying image attachments.
+ * The template for displaying image attachments
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link http://codex.wordpress.org/Template_Hierarchy
  *
  * @package WordPress
  * @subpackage Twenty_Twelve
@@ -74,6 +74,16 @@ else :
 endif;
 ?>
 								<a href="<?php echo esc_url( $next_attachment_url ); ?>" title="<?php the_title_attribute(); ?>" rel="attachment"><?php
+								/**
+ 								 * Filter the image attachment size to use.
+								 *
+								 * @since Twenty Twelve 1.0
+								 *
+								 * @param array $size {
+								 *     @type int The attachment height in pixels.
+								 *     @type int The attachment width in pixels.
+								 * }
+								 */
 								$attachment_size = apply_filters( 'twentytwelve_attachment_size', array( 960, 960 ) );
 								echo wp_get_attachment_image( $post->ID, $attachment_size );
 								?></a>

inc/custom-header.php

@@ -1,6 +1,7 @@
 <?php
 /**
- * Implements an optional custom header for Twenty Twelve.
+ * Implement an optional custom header for Twenty Twelve
+ *
  * See http://codex.wordpress.org/Custom_Headers
  *
  * @package WordPress
@@ -9,7 +10,7 @@
  */
 
 /**
- * Sets up the WordPress core custom header arguments and settings.
+ * Set up the WordPress core custom header arguments and settings.
  *
  * @uses add_theme_support() to register support for 3.4 and up.
  * @uses twentytwelve_header_style() to style front-end.
@@ -47,7 +48,7 @@ function twentytwelve_custom_header_setup() {
 add_action( 'after_setup_theme', 'twentytwelve_custom_header_setup' );
 
 /**
- * Loads our special font CSS file.
+ * Load our special font CSS file.
  *
  * @since Twenty Twelve 1.2
  *
@@ -61,7 +62,7 @@ function twentytwelve_custom_header_fonts() {
 add_action( 'admin_print_styles-appearance_page_custom-header', 'twentytwelve_custom_header_fonts' );
 
 /**
- * Styles the header text displayed on the blog.
+ * Style the header text displayed on the blog.
  *
  * get_header_textcolor() options: 515151 is default, hide text (returns 'blank'), or any hex value.
  *
@@ -101,7 +102,7 @@ function twentytwelve_header_style() {
 }
 
 /**
- * Styles the header image displayed on the Appearance > Header admin panel.
+ * Style the header image displayed on the Appearance > Header admin panel.
  *
  * @since Twenty Twelve 1.0
  */
@@ -141,7 +142,8 @@ function twentytwelve_admin_header_style() {
 }
 
 /**
- * Outputs markup to be displayed on the Appearance > Header admin panel.
+ * Output markup to be displayed on the Appearance > Header admin panel.
+ *
  * This callback overrides the default markup displayed there.
  *
  * @since Twenty Twelve 1.0

index.php

@@ -1,13 +1,13 @@
 <?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.
  * For example, 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_Twelve

page.php

@@ -1,6 +1,6 @@
 <?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

search.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The template for displaying Search Results pages.
+ * The template for displaying Search Results pages
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

sidebar-front.php

@@ -1,15 +1,15 @@
 <?php
 /**
- * The sidebar containing the front page widget areas.
+ * The sidebar containing the front page widget areas
  *
- * If no active widgets in either sidebar, they will be hidden completely.
+ * If no active widgets are in either sidebar, hide them completely.
  *
  * @package WordPress
  * @subpackage Twenty_Twelve
  * @since Twenty Twelve 1.0
  */
 
-/*
+/**
  * The front page widget area is triggered if any of the areas
  * have widgets. So let's check that first.
  *

sidebar.php

@@ -1,8 +1,8 @@
 <?php
 /**
- * The sidebar containing the main widget area.
+ * The sidebar containing the main widget area
  *
- * If no active widgets in sidebar, let's hide it completely.
+ * If no active widgets are in the sidebar, hide it completely.
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

single.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * The Template for displaying all single posts.
+ * The Template for displaying all single posts
  *
  * @package WordPress
  * @subpackage Twenty_Twelve

tag.php

@@ -1,10 +1,10 @@
 <?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_Twelve
@@ -29,7 +29,8 @@ get_header(); ?>
 			/* 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 to
 				 * this in a child theme then include a file called called content-___.php
 				 * (where ___ is the post format) and that will be used instead.
 				 */