From 4a9b21226c7a9a94a93adf94c455bdf7e64a52be Mon Sep 17 00:00:00 2001 From: Lance Willett Date: Fri, 20 Sep 2013 19:24:09 +0000 Subject: [PATCH] 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 --- wp-content/themes/twentytwelve/404.php | 2 +- wp-content/themes/twentytwelve/archive.php | 4 +- wp-content/themes/twentytwelve/author.php | 10 ++- wp-content/themes/twentytwelve/category.php | 4 +- wp-content/themes/twentytwelve/comments.php | 4 +- .../themes/twentytwelve/content-none.php | 2 +- .../themes/twentytwelve/content-status.php | 12 ++- wp-content/themes/twentytwelve/content.php | 16 +++- wp-content/themes/twentytwelve/footer.php | 5 +- wp-content/themes/twentytwelve/functions.php | 80 +++++++++++++------ wp-content/themes/twentytwelve/header.php | 2 +- wp-content/themes/twentytwelve/image.php | 14 +++- .../themes/twentytwelve/inc/custom-header.php | 14 ++-- wp-content/themes/twentytwelve/index.php | 4 +- wp-content/themes/twentytwelve/page.php | 2 +- wp-content/themes/twentytwelve/search.php | 2 +- .../themes/twentytwelve/sidebar-front.php | 6 +- wp-content/themes/twentytwelve/sidebar.php | 4 +- wp-content/themes/twentytwelve/single.php | 2 +- wp-content/themes/twentytwelve/tag.php | 7 +- 20 files changed, 134 insertions(+), 62 deletions(-) diff --git a/wp-content/themes/twentytwelve/404.php b/wp-content/themes/twentytwelve/404.php index e7270b4f40..db3ef811b2 100644 --- a/wp-content/themes/twentytwelve/404.php +++ b/wp-content/themes/twentytwelve/404.php @@ -1,6 +1,6 @@ if ( get_the_author_meta( 'description' ) ) : ?>
- +

diff --git a/wp-content/themes/twentytwelve/category.php b/wp-content/themes/twentytwelve/category.php index fc500867d5..0376977e65 100644 --- a/wp-content/themes/twentytwelve/category.php +++ b/wp-content/themes/twentytwelve/category.php @@ -1,10 +1,10 @@

- +
diff --git a/wp-content/themes/twentytwelve/content.php b/wp-content/themes/twentytwelve/content.php index bf2936ca21..6ba7261883 100644 --- a/wp-content/themes/twentytwelve/content.php +++ b/wp-content/themes/twentytwelve/content.php @@ -1,6 +1,8 @@
- +

diff --git a/wp-content/themes/twentytwelve/footer.php b/wp-content/themes/twentytwelve/footer.php index 91ca7927f5..79848d3424 100644 --- a/wp-content/themes/twentytwelve/footer.php +++ b/wp-content/themes/twentytwelve/footer.php @@ -1,9 +1,8 @@ '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 ); diff --git a/wp-content/themes/twentytwelve/header.php b/wp-content/themes/twentytwelve/header.php index 2d3dfa630f..a1deb4edc2 100644 --- a/wp-content/themes/twentytwelve/header.php +++ b/wp-content/themes/twentytwelve/header.php @@ -1,6 +1,6 @@ section and everything up till
* diff --git a/wp-content/themes/twentytwelve/image.php b/wp-content/themes/twentytwelve/image.php index b2fcb428ac..44e2f8c031 100644 --- a/wp-content/themes/twentytwelve/image.php +++ b/wp-content/themes/twentytwelve/image.php @@ -1,8 +1,8 @@ ID, $attachment_size ); ?> diff --git a/wp-content/themes/twentytwelve/inc/custom-header.php b/wp-content/themes/twentytwelve/inc/custom-header.php index 595bf98f5a..32fea17f79 100644 --- a/wp-content/themes/twentytwelve/inc/custom-header.php +++ b/wp-content/themes/twentytwelve/inc/custom-header.php @@ -1,6 +1,7 @@ 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 diff --git a/wp-content/themes/twentytwelve/index.php b/wp-content/themes/twentytwelve/index.php index 91201b447f..74b574ec12 100644 --- a/wp-content/themes/twentytwelve/index.php +++ b/wp-content/themes/twentytwelve/index.php @@ -1,13 +1,13 @@ /* 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. */