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

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


git-svn-id: http://core.svn.wordpress.org/trunk@25442 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Lance Willett 2013-09-20 19:34:10 +00:00
parent 4a9b21226c
commit d373d0982b
31 changed files with 144 additions and 90 deletions

View File

@ -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_Thirteen

View File

@ -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 @@
* 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_Thirteen

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Author bios.
* The template for displaying Author bios
*
* @package WordPress
* @subpackage Twenty_Thirteen
@ -10,7 +10,17 @@
<div class="author-info">
<div class="author-avatar">
<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentythirteen_author_bio_avatar_size', 74 ) ); ?>
<?php
/**
* Filter the author bio avatar size.
*
* @since Twenty Thirteen 1.0
*
* @param int $size The avatar height and width size in pixels.
*/
$author_bio_avatar_size = apply_filters( 'twentythirteen_author_bio_avatar_size', 74 );
echo get_avatar( get_the_author_meta( 'user_email' ), $author_bio_avatar_size );
?>
</div><!-- .author-avatar -->
<div class="author-description">
<h2 class="author-title"><?php printf( __( 'About %s', 'twentythirteen' ), get_the_author() ); ?></h2>

View File

@ -1,8 +1,8 @@
<?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_Thirteen
@ -17,8 +17,9 @@ get_header(); ?>
<?php if ( have_posts() ) : ?>
<?php
/* Queue the first post, that way we know
* what author we're dealing with (if that is the case).
/**
* 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 with a call to rewind_posts().
@ -31,7 +32,8 @@ get_header(); ?>
</header><!-- .archive-header -->
<?php
/* Since we called the_post() above, we need to
/**
* 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.
*/

View File

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

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Comments.
* The template for displaying Comments
*
* The area of the page that contains comments and the comment form.
*
@ -9,7 +9,7 @@
* @since Twenty Thirteen 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.
*/

View File

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

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying posts in the Audio post format.
* The template for displaying posts in the Audio post format
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying posts in the Chat post format.
* The template for displaying posts in the Chat post format
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

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

View File

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

View File

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

View File

@ -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_Thirteen

View File

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

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying posts in the Status post format.
* The template for displaying posts in the Status post format
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

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

View File

@ -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_Thirteen

View File

@ -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
* #main and #page div elements.
* Contains footer content and the closing of the #main and #page div elements.
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

@ -1,6 +1,6 @@
<?php
/**
* Twenty Thirteen functions and definitions.
* Twenty Thirteen 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 filter
@ -16,8 +16,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_Thirteen
@ -25,14 +24,15 @@
*/
/**
* 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 twentythirteen_content_width() for template-specific adjustments.
*/
if ( ! isset( $content_width ) )
$content_width = 604;
/**
* Adds support for a custom header image.
* Add support for a custom header image.
*/
require get_template_directory() . '/inc/custom-header.php';
@ -43,6 +43,8 @@ if ( version_compare( $GLOBALS['wp_version'], '3.6-alpha', '<' ) )
require get_template_directory() . '/inc/back-compat.php';
/**
* Twenty Thirteen setup.
*
* Sets up theme defaults and registers the various WordPress features that
* Twenty Thirteen supports.
*
@ -58,7 +60,7 @@ if ( version_compare( $GLOBALS['wp_version'], '3.6-alpha', '<' ) )
* @return void
*/
function twentythirteen_setup() {
/*
/**
* Makes Twenty Thirteen available for translation.
*
* Translations can be added to the /languages/ directory.
@ -68,7 +70,7 @@ function twentythirteen_setup() {
*/
load_theme_textdomain( 'twentythirteen', get_template_directory() . '/languages' );
/*
/**
* This theme styles the visual editor to resemble the theme style,
* specifically font, colors, icons, and column width.
*/
@ -77,11 +79,13 @@ function twentythirteen_setup() {
// Adds RSS feed links to <head> for posts and comments.
add_theme_support( 'automatic-feed-links' );
// Switches default core markup for search form, comment form, and comments
// to output valid HTML5.
/**
* Switches default core markup for search form, comment form,
* and comments to output valid HTML5.
*/
add_theme_support( 'html5', array( 'search-form', 'comment-form', 'comment-list' ) );
/*
/**
* This theme supports all available post formats by default.
* See http://codex.wordpress.org/Post_Formats
*/
@ -92,7 +96,7 @@ function twentythirteen_setup() {
// This theme uses wp_nav_menu() in one location.
register_nav_menu( 'primary', __( 'Navigation Menu', 'twentythirteen' ) );
/*
/**
* This theme uses a custom image size for featured images, displayed on
* "standard" posts and pages.
*/
@ -105,7 +109,7 @@ function twentythirteen_setup() {
add_action( 'after_setup_theme', 'twentythirteen_setup' );
/**
* Returns the Google font stylesheet URL, if available.
* Return the Google font stylesheet URL, if available.
*
* The use of Source Sans Pro and Bitter by default is localized. For languages
* that use characters not supported by the font, the font can be disabled.
@ -117,13 +121,15 @@ add_action( 'after_setup_theme', 'twentythirteen_setup' );
function twentythirteen_fonts_url() {
$fonts_url = '';
/* Translators: If there are characters in your language that are not
/**
* Translators: If there are characters in your language that are not
* supported by Source Sans Pro, translate this to 'off'. Do not translate
* into your own language.
*/
$source_sans_pro = _x( 'on', 'Source Sans Pro font: on or off', 'twentythirteen' );
/* Translators: If there are characters in your language that are not
/**
* Translators: If there are characters in your language that are not
* supported by Bitter, translate this to 'off'. Do not translate into your
* own language.
*/
@ -149,15 +155,17 @@ function twentythirteen_fonts_url() {
}
/**
* Enqueues scripts and styles for front end.
* Enqueue scripts and styles for the front end.
*
* @since Twenty Thirteen 1.0
*
* @return void
*/
function twentythirteen_scripts_styles() {
// Adds JavaScript to pages with the comment form to support sites with
// threaded comments (when in use).
/**
* 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' );
@ -184,13 +192,15 @@ function twentythirteen_scripts_styles() {
add_action( 'wp_enqueue_scripts', 'twentythirteen_scripts_styles' );
/**
* Filter the page title.
*
* Creates a nicely formatted and more specific title element text for output
* in head of document, based on current view.
*
* @since Twenty Thirteen 1.0
*
* @param string $title Default title text for current view.
* @param string $sep Optional separator.
* @param string $sep Optional separator.
* @return string The filtered title.
*/
function twentythirteen_wp_title( $title, $sep ) {
@ -216,7 +226,7 @@ function twentythirteen_wp_title( $title, $sep ) {
add_filter( 'wp_title', 'twentythirteen_wp_title', 10, 2 );
/**
* Registers two widget areas.
* Register two widget areas.
*
* @since Twenty Thirteen 1.0
*
@ -247,7 +257,7 @@ add_action( 'widgets_init', 'twentythirteen_widgets_init' );
if ( ! function_exists( 'twentythirteen_paging_nav' ) ) :
/**
* Displays navigation to next/previous set of posts when applicable.
* Display navigation to next/previous set of posts when applicable.
*
* @since Twenty Thirteen 1.0
*
@ -280,7 +290,7 @@ endif;
if ( ! function_exists( 'twentythirteen_post_nav' ) ) :
/**
* Displays navigation to next/previous post when applicable.
* Display navigation to next/previous post when applicable.
*
* @since Twenty Thirteen 1.0
*
@ -311,7 +321,7 @@ endif;
if ( ! function_exists( 'twentythirteen_entry_meta' ) ) :
/**
* Prints HTML with meta information for current post: categories, tags, permalink, author, and date.
* Print HTML with meta information for current post: categories, tags, permalink, author, and date.
*
* Create your own twentythirteen_entry_meta() to override in a child theme.
*
@ -351,13 +361,13 @@ endif;
if ( ! function_exists( 'twentythirteen_entry_date' ) ) :
/**
* Prints HTML with date information for current post.
* Print HTML with date information for current post.
*
* Create your own twentythirteen_entry_date() to override in a child theme.
*
* @since Twenty Thirteen 1.0
*
* @param boolean $echo Whether to echo the date. Default true.
* @param boolean $echo (optional) Whether to echo the date. Default true.
* @return string The HTML-formatted post date.
*/
function twentythirteen_entry_date( $echo = true ) {
@ -382,16 +392,26 @@ endif;
if ( ! function_exists( 'twentythirteen_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 Thirteen 1.0
*
* @return void
*/
function twentythirteen_the_attached_image() {
$post = get_post();
/**
* Filter the image attachment size to use.
*
* @since Twenty thirteen 1.0
*
* @param array $size {
* @type int The attachment height in pixels.
* @type int The attachment width in pixels.
* }
*/
$attachment_size = apply_filters( 'twentythirteen_attachment_size', array( 724, 724 ) );
$next_attachment_url = wp_get_attachment_url();
$post = get_post();
/**
* Grab the IDs of all the image attachments in a gallery so we can get the URL
@ -437,7 +457,7 @@ function twentythirteen_the_attached_image() {
endif;
/**
* Returns the URL from the post.
* Return the post URL.
*
* @uses get_url_in_content() to get the URL in the post meta (if it exists) or
* the first link found in the post content.
@ -456,7 +476,7 @@ function twentythirteen_get_link_url() {
}
/**
* Extends the default WordPress body classes.
* Extend the default WordPress body classes.
*
* Adds body classes to denote:
* 1. Single or multiple authors.
@ -483,7 +503,7 @@ function twentythirteen_body_class( $classes ) {
add_filter( 'body_class', 'twentythirteen_body_class' );
/**
* Adjusts content_width value for video post formats and attachment templates.
* Adjust content_width value for video post formats and attachment templates.
*
* @since Twenty Thirteen 1.0
*
@ -515,10 +535,14 @@ function twentythirteen_customize_register( $wp_customize ) {
add_action( 'customize_register', 'twentythirteen_customize_register' );
/**
* Binds JavaScript handlers to make Customizer preview reload changes
* asynchronously.
* Enqueue Javascript postMessage handlers for the Customizer.
*
* Binds JavaScript handlers to make the Customizer preview
* reload changes asynchronously.
*
* @since Twenty Thirteen 1.0
*
* @return void
*/
function twentythirteen_customize_preview_js() {
wp_enqueue_script( 'twentythirteen-customizer', get_template_directory_uri() . '/js/theme-customizer.js', array( 'customize-preview' ), '20130226', true );

View File

@ -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">
*

View File

@ -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_Thirteen

View File

@ -1,9 +1,9 @@
<?php
/**
* Twenty Thirteen back compat functionality.
* Twenty Thirteen back compat functionality
*
* Prevents Twenty Thirteen from running on WordPress versions prior to 3.6,
* since this theme is not meant to be backwards compatible and relies on
* since this theme is not meant to be backward compatible and relies on
* many new functions and markup changes introduced in 3.6.
*
* @package WordPress
@ -12,8 +12,9 @@
*/
/**
* Prevent switching to Twenty Thirteen on old versions of WordPress. Switches
* to the default theme.
* Prevent switching to Twenty Thirteen on old versions of WordPress.
*
* Switches to the default theme.
*
* @since Twenty Thirteen 1.0
*
@ -27,6 +28,8 @@ function twentythirteen_switch_theme() {
add_action( 'after_switch_theme', 'twentythirteen_switch_theme' );
/**
* Add message for unsuccessful theme switch.
*
* Prints an update nag after an unsuccessful attempt to switch to
* Twenty Thirteen on WordPress versions prior to 3.6.
*
@ -40,7 +43,7 @@ function twentythirteen_upgrade_notice() {
}
/**
* Prevents the Customizer from being loaded on WordPress versions prior to 3.6.
* Prevent the Theme Customizer from being loaded on WordPress versions prior to 3.6.
*
* @since Twenty Thirteen 1.0
*
@ -54,7 +57,7 @@ function twentythirteen_customize() {
add_action( 'load-customize.php', 'twentythirteen_customize' );
/**
* Prevents the Theme Preview from being loaded on WordPress versions prior to 3.4.
* Prevent the Theme Preview from being loaded on WordPress versions prior to 3.4.
*
* @since Twenty Thirteen 1.0
*
@ -65,4 +68,4 @@ function twentythirteen_preview() {
wp_die( sprintf( __( 'Twenty Thirteen requires at least WordPress version 3.6. You are running version %s. Please upgrade and try again.', 'twentythirteen' ), $GLOBALS['wp_version'] ) );
}
}
add_action( 'template_redirect', 'twentythirteen_preview' );
add_action( 'template_redirect', 'twentythirteen_preview' );

View File

@ -1,7 +1,8 @@
<?php
/**
* Implements a custom header for Twenty Thirteen.
* See http://codex.wordpress.org/Custom_Headers
* Implement a custom header for Twenty Thirteen
*
* @link http://codex.wordpress.org/Custom_Headers
*
* @package WordPress
* @subpackage Twenty_Thirteen
@ -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 twentythirteen_header_style() to style front-end.
@ -18,6 +19,8 @@
* @uses register_default_headers() to set up the bundled header images.
*
* @since Twenty Thirteen 1.0
*
* @return void
*/
function twentythirteen_custom_header_setup() {
$args = array(
@ -37,7 +40,7 @@ function twentythirteen_custom_header_setup() {
add_theme_support( 'custom-header', $args );
/*
/**
* Default custom headers packaged with the theme.
* %s is a placeholder for the theme template directory URI.
*/
@ -62,9 +65,11 @@ function twentythirteen_custom_header_setup() {
add_action( 'after_setup_theme', 'twentythirteen_custom_header_setup', 11 );
/**
* Loads our special font CSS files.
* Load our special font CSS files.
*
* @since Twenty Thirteen 1.0
*
* @return void
*/
function twentythirteen_custom_header_fonts() {
// Add Open Sans and Bitter fonts.
@ -76,11 +81,13 @@ function twentythirteen_custom_header_fonts() {
add_action( 'admin_print_styles-appearance_page_custom-header', 'twentythirteen_custom_header_fonts' );
/**
* Styles the header text displayed on the blog.
* Style the header text displayed on the blog.
*
* get_header_textcolor() options: Hide text (returns 'blank'), or any hex value.
*
* @since Twenty Thirteen 1.0
*
* @return void
*/
function twentythirteen_header_style() {
$header_image = get_header_image();
@ -134,9 +141,11 @@ function twentythirteen_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 Thirteen 1.0
*
* @return void
*/
function twentythirteen_admin_header_style() {
$header_image = get_header_image();
@ -198,10 +207,13 @@ function twentythirteen_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 Thirteen 1.0
*
* @return void
*/
function twentythirteen_admin_header_image() {
?>

View File

@ -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_Thirteen

View File

@ -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 and that other

View File

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

View File

@ -1,8 +1,8 @@
<?php
/**
* The sidebar containing the footer widget area.
* The sidebar containing the footer widget area
*
* If no active widgets in this sidebar, it will be hidden completely.
* If no active widgets in this sidebar, hide it completely.
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

@ -1,8 +1,10 @@
<?php
/**
* The sidebar containing the secondary widget area, displays on posts and pages.
* The sidebar containing the secondary widget area
*
* If no active widgets in this sidebar, it will be hidden completely.
* Displays on posts and pages.
*
* If no active widgets are in this sidebar, hide it completely.
*
* @package WordPress
* @subpackage Twenty_Thirteen

View File

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

View File

@ -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_Thirteen

View File

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