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

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


git-svn-id: http://core.svn.wordpress.org/trunk@25544 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Lance Willett 2013-09-25 17:04:10 +00:00
parent f3c9b36f73
commit 6268f714e0
21 changed files with 176 additions and 81 deletions

View File

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

View File

@ -1,11 +1,11 @@
<?php
/**
* The template for displaying Archive pages.
* 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.
*
* Learn more: http://codex.wordpress.org/Template_Hierarchy
* @link http://codex.wordpress.org/Template_Hierarchy
*
* @package WordPress
* @subpackage Twenty_Ten
@ -18,7 +18,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Queue the first post, that way we know
/**
* Queue the first post, that way we know
* what date we're dealing with (if that is the case).
*
* We reset this later so we can run the loop
@ -41,13 +42,15 @@ get_header(); ?>
</h1>
<?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.
*/
rewind_posts();
/* Run the loop for the archives page to output the posts.
/**
* Run the loop for the archives page to output the posts.
* If you want to overload this in a child theme then include a file
* called loop-archive.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying attachments.
* Template for displaying attachments
*
* @package WordPress
* @subpackage Twenty_Ten
@ -13,7 +13,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Run the loop to output the attachment.
/**
* Run the loop to output the attachment.
* If you want to overload this in a child theme then include a file
* called loop-attachment.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Author Archive pages.
* Template for displaying Author Archive pages
*
* @package WordPress
* @subpackage Twenty_Ten
@ -13,7 +13,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Queue the first post, that way we know who
/**
* Queue the first post, that way we know who
* the author is when we try to get their name,
* URL, description, avatar, etc.
*
@ -31,7 +32,16 @@ get_header(); ?>
if ( get_the_author_meta( 'description' ) ) : ?>
<div id="entry-author-info">
<div id="author-avatar">
<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) ); ?>
<?php
/**
* Filter the Twenty Ten author bio avatar size.
*
* @since Twenty Ten 1.0
*
* @param int The height and width avatar dimensions in pixels. Default 60.
*/
echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) );
?>
</div><!-- #author-avatar -->
<div id="author-description">
<h2><?php printf( __( 'About %s', 'twentyten' ), get_the_author() ); ?></h2>
@ -41,13 +51,15 @@ if ( get_the_author_meta( 'description' ) ) : ?>
<?php endif; ?>
<?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.
*/
rewind_posts();
/* Run the loop for the author archive page to output the authors posts
/**
* Run the loop for the author archive page to output the authors posts
* If you want to overload this in a child theme then include a file
* called loop-author.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Category Archive pages.
* Template for displaying Category Archive pages
*
* @package WordPress
* @subpackage Twenty_Ten
@ -20,7 +20,8 @@ get_header(); ?>
if ( ! empty( $category_description ) )
echo '<div class="archive-meta">' . $category_description . '</div>';
/* Run the loop for the category page to output the posts.
/**
* Run the loop for the category page to output the posts.
* If you want to overload this in a child theme then include a file
* called loop-category.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Comments.
* Template for displaying Comments
*
* The area of the page that contains both current comments
* and the comment form. The actual display of comments is
@ -18,7 +18,8 @@
<p class="nopassword"><?php _e( 'This post is password protected. Enter the password to view any comments.', 'twentyten' ); ?></p>
</div><!-- #comments -->
<?php
/* Stop the rest of comments.php from being processed,
/**
* Stop the rest of comments.php from being processed,
* but don't kill the script entirely -- we still have
* to fully load the template.
*/
@ -45,7 +46,8 @@
<ol class="commentlist">
<?php
/* Loop through and list the comments. Tell wp_list_comments()
/**
* Loop through and list the comments. Tell wp_list_comments()
* to use twentyten_comment() to format the comments.
* If you want to overload this in a child theme then you can
* define twentyten_comment() and that will be used instead.
@ -63,7 +65,8 @@
<?php endif; // check for comment navigation ?>
<?php
/* If there are no comments and comments are closed, let's leave a little note, shall we?
/**
* If there are no comments and comments are closed, let's leave a little note, shall we?
* But we only want the note on posts and pages that had comments in the first place.
*/
if ( ! comments_open() && get_comments_number() ) : ?>

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying the footer.
* Template for displaying the footer
*
* Contains the closing of the id=main div and all content
* after. Calls sidebar-footer.php for bottom widgets.
@ -16,7 +16,8 @@
<div id="colophon">
<?php
/* A sidebar in the footer? Yep. You can can customize
/**
* A sidebar in the footer? Yep. You can can customize
* your footer with four columns of widgets.
*/
get_sidebar( 'footer' );
@ -29,7 +30,13 @@
</div><!-- #site-info -->
<div id="site-generator">
<?php do_action( 'twentyten_credits' ); ?>
<?php
/**
* Fires before the Twenty Ten credits in the footer.
*
* @since Twenty Ten 1.0
*/
do_action( 'twentyten_credits' ); ?>
<a href="<?php echo esc_url( __( 'http://wordpress.org/', 'twentyten' ) ); ?>" title="<?php esc_attr_e( 'Semantic Personal Publishing Platform', 'twentyten' ); ?>"><?php printf( __( 'Proudly powered by %s.', 'twentyten' ), 'WordPress' ); ?></a>
</div><!-- #site-generator -->
@ -39,7 +46,8 @@
</div><!-- #wrapper -->
<?php
/* Always have wp_footer() just before the closing </body>
/**
* Always have wp_footer() just before the closing </body>
* tag of your theme, or you will break many plugins, which
* generally use this hook to reference JavaScript files.
*/

View File

@ -52,7 +52,7 @@ add_action( 'after_setup_theme', 'twentyten_setup' );
if ( ! function_exists( 'twentyten_setup' ) ):
/**
* Sets up theme defaults and registers support for various WordPress features.
* 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
@ -61,12 +61,12 @@ if ( ! function_exists( 'twentyten_setup' ) ):
* To override twentyten_setup() in a child theme, add your own twentyten_setup to your child theme's
* functions.php file.
*
* @uses add_theme_support() To add support for post thumbnails, custom headers and backgrounds, and automatic feed links.
* @uses register_nav_menus() To add support for navigation menus.
* @uses add_editor_style() To style the visual editor.
* @uses load_theme_textdomain() For translation/localization support.
* @uses add_theme_support() To add support for post thumbnails, custom headers and backgrounds, and automatic feed links.
* @uses register_nav_menus() To add support for navigation menus.
* @uses add_editor_style() To style the visual editor.
* @uses load_theme_textdomain() For translation/localization support.
* @uses register_default_headers() To register the default custom header images provided with the theme.
* @uses set_post_thumbnail_size() To set a custom post thumbnail size.
* @uses set_post_thumbnail_size() To set a custom post thumbnail size.
*
* @since Twenty Ten 1.0
*/
@ -84,8 +84,10 @@ function twentyten_setup() {
// Add default posts and comments RSS feed links to head
add_theme_support( 'automatic-feed-links' );
// Make theme available for translation
// Translations can be filed in the /languages/ directory
/**
* Make theme available for translation.
* Translations can be filed in the /languages/ directory
*/
load_theme_textdomain( 'twentyten', get_template_directory() . '/languages' );
// This theme uses wp_nav_menu() in one location.
@ -102,11 +104,27 @@ function twentyten_setup() {
// The custom header business starts here.
$custom_header_support = array(
// The default image to use.
// The %s is a placeholder for the theme template directory URI.
/**
* The default image to use.
* The %s is a placeholder for the theme template directory URI.
*/
'default-image' => '%s/images/headers/path.jpg',
// The height and width of our custom header.
/**
* Filter the Twenty Ten default header image width.
*
* @since Twenty Ten 1.0
*
* @param int The default header image width in pixels. Default 940.
*/
'width' => apply_filters( 'twentyten_header_image_width', 940 ),
/**
* Filter the Twenty Ten defaul header image height.
*
* @since Twenty Ten 1.0
*
* @param int The default header image height in pixels. Default 198.
*/
'height' => apply_filters( 'twentyten_header_image_height', 198 ),
// Support flexible heights.
'flex-height' => true,
@ -129,9 +147,11 @@ function twentyten_setup() {
add_custom_background();
}
// We'll be using post thumbnails for custom header images on posts and pages.
// We want them to be 940 pixels wide by 198 pixels tall.
// Larger images will be auto-cropped to fit, smaller ones will be ignored. See header.php.
/**
* We'll be using post thumbnails for custom header images on posts and pages.
* We want them to be 940 pixels wide by 198 pixels tall.
* Larger images will be auto-cropped to fit, smaller ones will be ignored. See header.php.
*/
set_post_thumbnail_size( $custom_header_support['width'], $custom_header_support['height'], true );
// ... and thus ends the custom header business.
@ -192,7 +212,7 @@ endif;
if ( ! function_exists( 'twentyten_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.
*
* Referenced via add_custom_image_header() in twentyten_setup().
*
@ -216,12 +236,14 @@ function twentyten_admin_header_style() {
endif;
/**
* Get our wp_nav_menu() fallback, wp_page_menu(), to show a home link.
* Show a home link for our wp_nav_menu() fallback, wp_page_menu().
*
* To override this in a child theme, remove the filter and optionally add
* your own function tied to the wp_page_menu_args filter hook.
*
* @since Twenty Ten 1.0
*
* @param array $args An optional array of arguments. @see wp_page_menu()
*/
function twentyten_page_menu_args( $args ) {
if ( ! isset( $args['show_home'] ) )
@ -231,13 +253,15 @@ function twentyten_page_menu_args( $args ) {
add_filter( 'wp_page_menu_args', 'twentyten_page_menu_args' );
/**
* Sets the post excerpt length to 40 characters.
* Set the post excerpt length to 40 characters.
*
* To override this length in a child theme, remove the filter and add your own
* function tied to the excerpt_length filter hook.
*
* @since Twenty Ten 1.0
* @return int
*
* @param int $length The number of excerpt characters.
* @return int The filtered number of excerpt characters.
*/
function twentyten_excerpt_length( $length ) {
return 40;
@ -246,10 +270,11 @@ add_filter( 'excerpt_length', 'twentyten_excerpt_length' );
if ( ! function_exists( 'twentyten_continue_reading_link' ) ) :
/**
* Returns a "Continue Reading" link for excerpts
* Return a "Continue Reading" link for excerpts.
*
* @since Twenty Ten 1.0
* @return string "Continue Reading" link
*
* @return string "Continue Reading" link.
*/
function twentyten_continue_reading_link() {
return ' <a href="'. get_permalink() . '">' . __( 'Continue reading <span class="meta-nav">&rarr;</span>', 'twentyten' ) . '</a>';
@ -257,13 +282,17 @@ function twentyten_continue_reading_link() {
endif;
/**
* Replaces "[...]" (appended to automatically generated excerpts) with an ellipsis and twentyten_continue_reading_link().
* Replace "[...]" with an ellipsis and twentyten_continue_reading_link().
*
* "[...]" is appended to automatically generated excerpts.
*
* To override this in a child theme, remove the filter and add your own
* function tied to the excerpt_more filter hook.
*
* @since Twenty Ten 1.0
* @return string An ellipsis
*
* @param string $more The Read More text.
* @return string An ellipsis.
*/
function twentyten_auto_excerpt_more( $more ) {
return ' &hellip;' . twentyten_continue_reading_link();
@ -271,13 +300,15 @@ function twentyten_auto_excerpt_more( $more ) {
add_filter( 'excerpt_more', 'twentyten_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 Ten 1.0
* @return string Excerpt with a pretty "Continue Reading" link
*
* @param string $output The "Coninue Reading" link.
* @return string Excerpt with a pretty "Continue Reading" link.
*/
function twentyten_custom_excerpt_more( $output ) {
if ( has_excerpt() && ! is_attachment() ) {
@ -325,6 +356,10 @@ if ( ! function_exists( 'twentyten_comment' ) ) :
* Used as a callback by wp_list_comments() for displaying the comments.
*
* @since Twenty Ten 1.0
*
* @param object $comment The comment object.
* @param array $args An array of arguments. @see get_comment_reply_link()
* @param int $depth The depth of the comment.
*/
function twentyten_comment( $comment, $args, $depth ) {
$GLOBALS['comment'] = $comment;
@ -376,7 +411,8 @@ endif;
* function tied to the init hook.
*
* @since Twenty Ten 1.0
* @uses register_sidebar
*
* @uses register_sidebar()
*/
function twentyten_widgets_init() {
// Area 1, located at the top of the sidebar.
@ -449,7 +485,7 @@ function twentyten_widgets_init() {
add_action( 'widgets_init', 'twentyten_widgets_init' );
/**
* Removes the default styles that are packaged with the Recent Comments widget.
* Remove the default styles that are packaged with the Recent Comments widget.
*
* To override this in a child theme, remove the filter and optionally add your own
* function tied to the widgets_init action hook.
@ -467,7 +503,7 @@ add_action( 'widgets_init', 'twentyten_remove_recent_comments_style' );
if ( ! function_exists( 'twentyten_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 Ten 1.0
*/
@ -490,7 +526,7 @@ endif;
if ( ! function_exists( 'twentyten_posted_in' ) ) :
/**
* Prints HTML with meta information for the current post (category, tags and permalink).
* Print HTML with meta information for the current post (category, tags and permalink).
*
* @since Twenty Ten 1.0
*/
@ -516,10 +552,10 @@ function twentyten_posted_in() {
endif;
/**
* Retrieves the IDs for images in a gallery.
* Retrieve the IDs for images in a gallery.
*
* @uses get_post_galleries() first, if available. Falls back to shortcode parsing,
* then as last option uses a get_posts() call.
* @uses get_post_galleries() First, if available. Falls back to shortcode parsing,
* then as last option uses a get_posts() call.
*
* @since Twenty Ten 1.6.
*

View File

@ -1,8 +1,8 @@
<?php
/**
* The Header for our theme.
* Header template for our theme
*
* Displays all of the <head> section and everything up till <div id="main">
* Displays all of the <head> section and everything up till <div id="main">.
*
* @package WordPress
* @subpackage Twenty_Ten
@ -37,13 +37,15 @@
<link rel="stylesheet" type="text/css" media="all" href="<?php bloginfo( 'stylesheet_url' ); ?>" />
<link rel="pingback" href="<?php bloginfo( 'pingback_url' ); ?>" />
<?php
/* We add some JavaScript to pages with the comment form
/**
* We add some JavaScript to pages with the comment form
* to support sites with threaded comments (when in use).
*/
if ( is_singular() && get_option( 'thread_comments' ) )
wp_enqueue_script( 'comment-reply' );
/* Always have wp_head() just before the closing </head>
/**
* Always have wp_head() just before the closing </head>
* tag of your theme, or you will break many plugins, which
* generally use this hook to add elements to <head> such
* as styles, scripts, and meta tags.
@ -68,8 +70,10 @@
<?php
// Compatibility with versions of WordPress prior to 3.4.
if ( function_exists( 'get_custom_header' ) ) {
// We need to figure out what the minimum width should be for our featured image.
// This result would be the suggested width if the theme were to implement flexible widths.
/**
* We need to figure out what the minimum width should be for our featured image.
* This result would be the suggested width if the theme were to implement flexible widths.
*/
$header_image_width = get_theme_support( 'custom-header', 'width' );
} else {
$header_image_width = HEADER_IMAGE_WIDTH;

View File

@ -1,6 +1,6 @@
<?php
/**
* The main template file.
* 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).
@ -19,7 +19,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Run the loop to output the posts.
/**
* Run the loop to output the posts.
* If you want to overload this in a child theme then include a file
* called loop-index.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The loop that displays an attachment.
* The loop that displays an attachment
*
* The loop displays the posts and the post content. See
* http://codex.wordpress.org/The_Loop to understand it and
@ -86,7 +86,21 @@
}
?>
<p class="attachment"><a href="<?php echo $next_attachment_url; ?>" title="<?php the_title_attribute(); ?>" rel="attachment"><?php
/**
* Filter the Twenty Ten default attachment width.
*
* @since Twenty Ten 1.0
*
* @param int The default attachment width in pixels. Default 900.
*/
$attachment_width = apply_filters( 'twentyten_attachment_size', 900 );
/**
* Filter the Twenty Ten default attachment height.
*
* @since Twenty Ten 1.0
*
* @param int The default attachment height in pixels. Default 900.
*/
$attachment_height = apply_filters( 'twentyten_attachment_height', 900 );
echo wp_get_attachment_image( $post->ID, array( $attachment_width, $attachment_height ) ); // filterable image width with, essentially, no limit for image height.
?></a></p>

View File

@ -1,6 +1,6 @@
<?php
/**
* The loop that displays a page.
* The loop that displays a page
*
* The loop displays the posts and the post content. See
* http://codex.wordpress.org/The_Loop to understand it and

View File

@ -1,6 +1,6 @@
<?php
/**
* The loop that displays a single post.
* The loop that displays a single post
*
* The loop displays the posts and the post content. See
* http://codex.wordpress.org/The_Loop to understand it and
@ -37,7 +37,10 @@
<?php if ( get_the_author_meta( 'description' ) ) : // If a user has filled out their description, show a bio on their entries ?>
<div id="entry-author-info">
<div id="author-avatar">
<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) ); ?>
<?php
//duplicate_hook
echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) );
?>
</div><!-- #author-avatar -->
<div id="author-description">
<h2><?php printf( __( 'About %s', 'twentyten' ), get_the_author() ); ?></h2>

View File

@ -1,6 +1,6 @@
<?php
/**
* The loop that displays posts.
* The loop that displays posts
*
* The loop displays the posts and the post content. See
* http://codex.wordpress.org/The_Loop to understand it and
@ -39,7 +39,8 @@
<?php endif; ?>
<?php
/* Start the Loop.
/**
* Start the Loop.
*
* In Twenty Ten we use the same loop in multiple contexts.
* It is broken into three main parts: when we're displaying
@ -52,7 +53,8 @@
* the rest of the loop that is shared.
*
* Without further ado, the loop:
*/ ?>
*/
?>
<?php while ( have_posts() ) : the_post(); ?>
<?php /* How to display posts of the Gallery format. The gallery category is the old way. */ ?>

View File

@ -18,7 +18,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Run the loop to output the page.
/**
* Run the loop to output the page.
* If you want to overload this in a child theme then include a file
* called loop-page.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying all pages.
* 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
@ -18,7 +18,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Run the loop to output the page.
/**
* Run the loop to output the page.
* If you want to overload this in a child theme then include a file
* called loop-page.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Search Results pages.
* Template for displaying Search Results pages
*
* @package WordPress
* @subpackage Twenty_Ten
@ -15,7 +15,8 @@ get_header(); ?>
<?php if ( have_posts() ) : ?>
<h1 class="page-title"><?php printf( __( 'Search Results for: %s', 'twentyten' ), '<span>' . get_search_query() . '</span>' ); ?></h1>
<?php
/* Run the loop for the search to output the results.
/**
* Run the loop for the search to output the results.
* If you want to overload this in a child theme then include a file
* called loop-search.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The Footer widget areas.
* The Footer widget areas
*
* @package WordPress
* @subpackage Twenty_Ten
@ -9,7 +9,8 @@
?>
<?php
/* The footer widget area is triggered if any of the areas
/**
* The footer widget area is triggered if any of the areas
* have widgets. So let's check that first.
*
* If none of the sidebars have widgets, then let's bail early.

View File

@ -1,6 +1,6 @@
<?php
/**
* The Sidebar containing the primary and secondary widget areas.
* Sidebar template containing the primary and secondary widget areas
*
* @package WordPress
* @subpackage Twenty_Ten
@ -12,7 +12,8 @@
<ul class="xoxo">
<?php
/* When we call the dynamic_sidebar() function, it'll spit out
/**
* When we call the dynamic_sidebar() function, it'll spit out
* the widgets for that widget area. If it instead returns false,
* then the sidebar simply doesn't exist, so we'll hard-code in
* some default sidebar stuff just in case.

View File

@ -1,6 +1,6 @@
<?php
/**
* The Template for displaying all single posts.
* Template for displaying all single posts
*
* @package WordPress
* @subpackage Twenty_Ten
@ -13,7 +13,8 @@ get_header(); ?>
<div id="content" role="main">
<?php
/* Run the loop to output the post.
/**
* Run the loop to output the post.
* If you want to overload this in a child theme then include a file
* called loop-single.php and that will be used instead.
*/

View File

@ -1,6 +1,6 @@
<?php
/**
* The template for displaying Tag Archive pages.
* Template for displaying Tag Archive pages
*
* @package WordPress
* @subpackage Twenty_Ten
@ -17,7 +17,8 @@ get_header(); ?>
?></h1>
<?php
/* Run the loop for the tag archive to output the posts
/**
* Run the loop for the tag archive to output the posts
* If you want to overload this in a child theme then include a file
* called loop-tag.php and that will be used instead.
*/