From 3ec703a6d112e92b4513df4ca17f6b04005b7f74 Mon Sep 17 00:00:00 2001 From: Lance Willett Date: Sat, 25 Aug 2012 16:53:32 +0000 Subject: [PATCH] Twenty Twelve: review and clarify code commenting and documentation. Props jorbin and obenland. See #21675. git-svn-id: http://core.svn.wordpress.org/trunk@21617 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- .../themes/twentytwelve/editor-style-rtl.css | 5 +- .../themes/twentytwelve/editor-style.css | 6 +- wp-content/themes/twentytwelve/functions.php | 76 ++++++++++--------- .../themes/twentytwelve/inc/custom-header.php | 17 +++-- .../themes/twentytwelve/inc/theme-options.php | 16 ++-- wp-content/themes/twentytwelve/rtl.css | 7 +- .../themes/twentytwelve/sidebar-home.php | 12 +-- wp-content/themes/twentytwelve/sidebar.php | 4 +- 8 files changed, 73 insertions(+), 70 deletions(-) diff --git a/wp-content/themes/twentytwelve/editor-style-rtl.css b/wp-content/themes/twentytwelve/editor-style-rtl.css index 2b20acbbe8..5fd832c6ff 100644 --- a/wp-content/themes/twentytwelve/editor-style-rtl.css +++ b/wp-content/themes/twentytwelve/editor-style-rtl.css @@ -1,8 +1,7 @@ /* Theme Name: Twenty Twelve - -Used to style the TinyMCE editor for RTL languages. -See also rtl.css +Description: Used to style the TinyMCE editor for RTL languages. +See also rtl.css file. */ html .mceContentBody { diff --git a/wp-content/themes/twentytwelve/editor-style.css b/wp-content/themes/twentytwelve/editor-style.css index 8ddb1d9042..4185347605 100644 --- a/wp-content/themes/twentytwelve/editor-style.css +++ b/wp-content/themes/twentytwelve/editor-style.css @@ -1,6 +1,6 @@ -/** -* Theme Name: Twenty Twelve -* Description: Used to style the TinyMCE editor. +/* +Theme Name: Twenty Twelve +Description: Used to style the TinyMCE editor. */ html { diff --git a/wp-content/themes/twentytwelve/functions.php b/wp-content/themes/twentytwelve/functions.php index 19636a1328..674da8734b 100644 --- a/wp-content/themes/twentytwelve/functions.php +++ b/wp-content/themes/twentytwelve/functions.php @@ -1,14 +1,11 @@ . + // Adds RSS feed links to for posts and comments. add_theme_support( 'automatic-feed-links' ); - // Add support for a variety of post formats + // This theme supports a variety of post formats. add_theme_support( 'post-formats', array( 'aside', 'image', 'link', 'quote' ) ); // This theme uses wp_nav_menu() in one location. register_nav_menu( 'primary', __( 'Primary Menu', 'twentytwelve' ) ); - // Add support for custom background. + /* + * This theme supports custom background color and image, and here + * we also set up the default background color. + */ add_theme_support( 'custom-background', array( 'default-color' => 'e6e6e6', ) ); - // Add custom image size for featured image use, displayed on "standard" posts. + // This theme uses a custom image size for featured images, displayed on "standard" posts. add_theme_support( 'post-thumbnails' ); set_post_thumbnail_size( 624, 9999 ); // Unlimited height, soft crop } add_action( 'after_setup_theme', 'twentytwelve_setup' ); /** - * Add support for a custom header image. + * Adds support for a custom header image. */ require( get_template_directory() . '/inc/custom-header.php' ); /** - * Enqueue scripts and styles for front-end. + * Enqueues scripts and styles for front-end. * * @since Twenty Twelve 1.0 */ function twentytwelve_scripts_styles() { global $twentytwelve_options; - /** - * Add JavaScript to pages with the comment form to support + /* + * 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' ); - /** - * JavaScript for handling navigation menus and the resized - * styles for small screen sizes. + /* + * Adds JavaScript for handling the navigation menu hide-and-show behavior. */ wp_enqueue_script( 'twentytwelve-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20120824', true ); - /** - * Load special font CSS file. + /* + * Loads our special font CSS file. * Depends on Theme Options setting. */ $options = $twentytwelve_options->get_theme_options(); if ( $options['enable_fonts'] ) wp_enqueue_style( 'twentytwelve-fonts', $twentytwelve_options->custom_fonts_url(), array(), null ); - /** - * Load our main CSS file. + /* + * Loads our main stylesheet. */ wp_enqueue_style( 'twentytwelve-style', get_stylesheet_uri() ); - /** - * Load HTML5 shiv for older IE version support for HTML5 elements. + /* + * Loads HTML5 JavaScript file to add support for HTML5 elements in older IE versions. * Ideally, should load after main CSS file. - * * See html5.js link in header.php. * * TODO depends on IE dependency being in core for JS enqueuing @@ -164,7 +165,7 @@ function twentytwelve_wp_title( $title, $sep ) { add_filter( 'wp_title', 'twentytwelve_wp_title', 10, 2 ); /** - * Get our wp_nav_menu() fallback, wp_page_menu(), to show a home link. + * Makes our wp_nav_menu() fallback -- wp_page_menu() -- show a home link. * * @since Twenty Twelve 1.0 */ @@ -175,7 +176,7 @@ function twentytwelve_page_menu_args( $args ) { add_filter( 'wp_page_menu_args', 'twentytwelve_page_menu_args' ); /** - * Register our single widget area. + * Registers our main widget area and the homepage widget areas. * * @since Twenty Twelve 1.0 */ @@ -213,7 +214,7 @@ function twentytwelve_widgets_init() { add_action( 'widgets_init', 'twentytwelve_widgets_init' ); /** - * Count the number of footer sidebars to enable dynamic classes for the footer + * Counts the number of footer sidebars to enable dynamic classes for the footer. * * @since Twenty Twelve 1.0 */ @@ -228,7 +229,7 @@ function twentytwelve_homepage_sidebar_class() { if ( ! function_exists( 'twentytwelve_content_nav' ) ) : /** - * Display navigation to next/previous pages when applicable. + * Displays navigation to next/previous pages when applicable. * * @since Twenty Twelve 1.0 */ @@ -364,6 +365,9 @@ endif; * 3. White or empty background color to change the layout and spacing. * * @since Twenty Twelve 1.0 + * + * @param array Existing class values. + * @return array Filtered class values. */ function twentytwelve_body_class( $classes ) { $background_color = get_background_color(); @@ -384,8 +388,8 @@ function twentytwelve_body_class( $classes ) { add_filter( 'body_class', 'twentytwelve_body_class' ); /** - * Adjust $content width for full-width and single image attachment templates - * and when there are no active widgets in the sidebar. + * 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 */ diff --git a/wp-content/themes/twentytwelve/inc/custom-header.php b/wp-content/themes/twentytwelve/inc/custom-header.php index 38733a1bf6..70affba466 100644 --- a/wp-content/themes/twentytwelve/inc/custom-header.php +++ b/wp-content/themes/twentytwelve/inc/custom-header.php @@ -1,7 +1,7 @@ Header admin panel. + * Outputs 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/inc/theme-options.php b/wp-content/themes/twentytwelve/inc/theme-options.php index b7bad93903..d923377e67 100644 --- a/wp-content/themes/twentytwelve/inc/theme-options.php +++ b/wp-content/themes/twentytwelve/inc/theme-options.php @@ -26,7 +26,7 @@ class Twenty_Twelve_Options { public $options = array(); /** - * Constructor + * Constructor. * * @access public * @@ -44,7 +44,7 @@ class Twenty_Twelve_Options { } /** - * Register the form setting for our options array. + * Registers the form setting for our options array. * * This function is attached to the admin_init action hook. * @@ -86,7 +86,7 @@ class Twenty_Twelve_Options { } /** - * Add our theme options page to the admin menu. + * Adds our theme options page to the admin menu. * * This function is attached to the admin_menu action hook. * @@ -148,7 +148,7 @@ class Twenty_Twelve_Options { } /** - * Returns the options array. + * Displays the theme options page. * * @uses get_current_theme() for back compat, fallback for < 3.4 * @access public @@ -175,7 +175,7 @@ class Twenty_Twelve_Options { } /** - * Sanitize and validate form input. Accepts an array, return a sanitized array. + * Sanitizes and validates form input. * * @see options_init() * @access public @@ -195,7 +195,7 @@ class Twenty_Twelve_Options { } /** - * Implement Twenty Twelve theme options into Theme Customizer. + * Implements Twenty Twelve theme options into Theme Customizer. * * @since Twenty Twelve 1.0 * @access public @@ -233,7 +233,7 @@ class Twenty_Twelve_Options { } /** - * Bind JS handlers to make Theme Customizer preview reload changes asynchronously. + * Binds JS handlers to make Theme Customizer preview reload changes asynchronously. * * @since Twenty Twelve 1.0 * @access public @@ -249,7 +249,7 @@ class Twenty_Twelve_Options { } /** - * Create path to load fonts CSS file with correct protocol. + * Creates path to load fonts CSS file with correct protocol. * * @since Twenty Twelve 1.0 * @access public diff --git a/wp-content/themes/twentytwelve/rtl.css b/wp-content/themes/twentytwelve/rtl.css index d67a36bab5..206e38845e 100644 --- a/wp-content/themes/twentytwelve/rtl.css +++ b/wp-content/themes/twentytwelve/rtl.css @@ -1,11 +1,10 @@ /* Theme Name: Twenty Twelve - -Adding support for language written in a Right To Left (RTL) direction is easy - -it's just a matter of overwriting all the horizontal positioning attributes +Description: Adds support for languages written in a Right To Left (RTL) direction. +It's easy, just a matter of overwriting all the horizontal positioning attributes of your CSS stylesheet in a separate stylesheet file named rtl.css. -http://codex.wordpress.org/Right_to_Left_Language_Support +See http://codex.wordpress.org/Right_to_Left_Language_Support */ diff --git a/wp-content/themes/twentytwelve/sidebar-home.php b/wp-content/themes/twentytwelve/sidebar-home.php index 1255852d21..b46a1f5d09 100644 --- a/wp-content/themes/twentytwelve/sidebar-home.php +++ b/wp-content/themes/twentytwelve/sidebar-home.php @@ -1,6 +1,6 @@