Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit 3ec703a6d112e92b4513df4ca17f6b04005b7f74 1 parent 8932111
authored August 25, 2012
5  wp-content/themes/twentytwelve/editor-style-rtl.css
... ...
@@ -1,8 +1,7 @@
1 1
 /*
2 2
 Theme Name: Twenty Twelve
3  
-
4  
-Used to style the TinyMCE editor for RTL languages.
5  
-See also rtl.css
  3
+Description: Used to style the TinyMCE editor for RTL languages.
  4
+See also rtl.css file.
6 5
 */
7 6
 
8 7
 html .mceContentBody {
6  wp-content/themes/twentytwelve/editor-style.css
... ...
@@ -1,6 +1,6 @@
1  
-/**
2  
-* Theme Name: Twenty Twelve
3  
-* Description: Used to style the TinyMCE editor.
  1
+/*
  2
+Theme Name: Twenty Twelve
  3
+Description: Used to style the TinyMCE editor.
4 4
 */
5 5
 
6 6
 html {
76  wp-content/themes/twentytwelve/functions.php
... ...
@@ -1,14 +1,11 @@
1 1
 <?php
2 2
 /**
3  
- * Twenty Twelve functions and definitions
  3
+ * Twenty Twelve functions and definitions.
4 4
  *
5  
- * Sets up the theme and provides some helper functions. Some helper functions
6  
- * are used in the theme as custom template tags. Others are attached to action and
  5
+ * Sets up the theme and provides some helper functions, which are used
  6
+ * in the theme as custom template tags. Others are attached to action and
7 7
  * filter hooks in WordPress to change core functionality.
8 8
  *
9  
- * The first function, twentytwelve_setup(), sets up the theme by registering support
10  
- * for various features in WordPress, such as a custom background and a navigation menu.
11  
- *
12 9
  * When using a child theme (see http://codex.wordpress.org/Theme_Development and
13 10
  * http://codex.wordpress.org/Child_Themes), you can override certain functions
14 11
  * (those wrapped in a function_exists() call) by defining them first in your child theme's
@@ -26,17 +23,19 @@
26 23
  */
27 24
 
28 25
 /**
29  
- * Set the content width based on the theme's design and stylesheet.
  26
+ * Sets up the content width value based on the theme's design and stylesheet.
30 27
  */
31 28
 if ( ! isset( $content_width ) )
32 29
 	$content_width = 625;
33 30
 
34 31
 /**
35  
- * Sets up theme defaults and registers support for various WordPress features.
  32
+ * Sets up theme defaults and registers the various WordPress features that
  33
+ * Twenty Twelve supports.
36 34
  *
37 35
  * @uses load_theme_textdomain() For translation/localization support.
38  
- * @uses add_theme_support() To add support for post thumbnails, automatic feed links, custom headers
39  
- * 	and backgrounds, and post formats.
  36
+ * @uses add_editor_style() To add a Visual Editor stylesheet.
  37
+ * @uses add_theme_support() To add support for post thumbnails, automatic feed links,
  38
+ * 	custom background, and post formats.
40 39
  * @uses register_nav_menu() To add support for navigation menus.
41 40
  * @uses set_post_thumbnail_size() To set a custom post thumbnail size.
42 41
  *
@@ -45,8 +44,9 @@
45 44
 function twentytwelve_setup() {
46 45
 	global $twentytwelve_options;
47 46
 
48  
-	/**
49  
-	 * Make Twenty Twelve available for translation.
  47
+	/*
  48
+	 * Makes Twenty Twelve available for translation.
  49
+	 *
50 50
 	 * Translations can be added to the /languages/ directory.
51 51
 	 * If you're building a theme based on Twenty Twelve, use a find and replace
52 52
 	 * to change 'twentytwelve' to the name of your theme in all the template files.
@@ -60,69 +60,70 @@ function twentytwelve_setup() {
60 60
 	// This theme styles the visual editor with editor-style.css to match the theme style.
61 61
 	add_editor_style();
62 62
 
63  
-	// Add default posts and comments RSS feed links to <head>.
  63
+	// Adds RSS feed links to <head> for posts and comments.
64 64
 	add_theme_support( 'automatic-feed-links' );
65 65
 
66  
-	// Add support for a variety of post formats
  66
+	// This theme supports a variety of post formats.
67 67
 	add_theme_support( 'post-formats', array( 'aside', 'image', 'link', 'quote' ) );
68 68
 
69 69
 	// This theme uses wp_nav_menu() in one location.
70 70
 	register_nav_menu( 'primary', __( 'Primary Menu', 'twentytwelve' ) );
71 71
 
72  
-	// Add support for custom background.
  72
+	/*
  73
+	 * This theme supports custom background color and image, and here
  74
+	 * we also set up the default background color.
  75
+	 */
73 76
 	add_theme_support( 'custom-background', array(
74 77
 		'default-color' => 'e6e6e6',
75 78
 	) );
76 79
 
77  
-	// Add custom image size for featured image use, displayed on "standard" posts.
  80
+	// This theme uses a custom image size for featured images, displayed on "standard" posts.
78 81
 	add_theme_support( 'post-thumbnails' );
79 82
 	set_post_thumbnail_size( 624, 9999 ); // Unlimited height, soft crop
80 83
 }
81 84
 add_action( 'after_setup_theme', 'twentytwelve_setup' );
82 85
 
83 86
 /**
84  
- * Add support for a custom header image.
  87
+ * Adds support for a custom header image.
85 88
  */
86 89
 require( get_template_directory() . '/inc/custom-header.php' );
87 90
 
88 91
 /**
89  
- * Enqueue scripts and styles for front-end.
  92
+ * Enqueues scripts and styles for front-end.
90 93
  *
91 94
  * @since Twenty Twelve 1.0
92 95
  */
93 96
 function twentytwelve_scripts_styles() {
94 97
 	global $twentytwelve_options;
95 98
 
96  
-	/**
97  
-	 * Add JavaScript to pages with the comment form to support
  99
+	/*
  100
+	 * Adds JavaScript to pages with the comment form to support
98 101
 	 * sites with threaded comments (when in use).
99 102
 	 */
100 103
 	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) )
101 104
 		wp_enqueue_script( 'comment-reply' );
102 105
 
103  
-	/**
104  
-	 * JavaScript for handling navigation menus and the resized
105  
-	 * styles for small screen sizes.
  106
+	/*
  107
+	 * Adds JavaScript for handling the navigation menu hide-and-show behavior.
106 108
 	 */
107 109
 	wp_enqueue_script( 'twentytwelve-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20120824', true );
108 110
 
109  
-	/**
110  
-	 * Load special font CSS file.
  111
+	/*
  112
+	 * Loads our special font CSS file.
111 113
 	 * Depends on Theme Options setting.
112 114
  	 */
113 115
 	$options = $twentytwelve_options->get_theme_options();
114 116
 	if ( $options['enable_fonts'] )
115 117
 		wp_enqueue_style( 'twentytwelve-fonts', $twentytwelve_options->custom_fonts_url(), array(), null );
116 118
 
117  
-	/**
118  
-	 * Load our main CSS file.
  119
+	/*
  120
+	 * Loads our main stylesheet.
119 121
 	 */
120 122
 	wp_enqueue_style( 'twentytwelve-style', get_stylesheet_uri() );
121 123
 
122  
-	/**
123  
-	 * Load HTML5 shiv for older IE version support for HTML5 elements.
  124
+	/*
  125
+	 * Loads HTML5 JavaScript file to add support for HTML5 elements in older IE versions.
124 126
 	 * Ideally, should load after main CSS file.
125  
-	 *
126 127
 	 * See html5.js link in header.php.
127 128
 	 *
128 129
 	 * TODO depends on IE dependency being in core for JS enqueuing
@@ -164,7 +165,7 @@ function twentytwelve_wp_title( $title, $sep ) {
164 165
 add_filter( 'wp_title', 'twentytwelve_wp_title', 10, 2 );
165 166
 
166 167
 /**
167  
- * Get our wp_nav_menu() fallback, wp_page_menu(), to show a home link.
  168
+ * Makes our wp_nav_menu() fallback -- wp_page_menu() -- show a home link.
168 169
  *
169 170
  * @since Twenty Twelve 1.0
170 171
  */
@@ -175,7 +176,7 @@ function twentytwelve_page_menu_args( $args ) {
175 176
 add_filter( 'wp_page_menu_args', 'twentytwelve_page_menu_args' );
176 177
 
177 178
 /**
178  
- * Register our single widget area.
  179
+ * Registers our main widget area and the homepage widget areas.
179 180
  *
180 181
  * @since Twenty Twelve 1.0
181 182
  */
@@ -213,7 +214,7 @@ function twentytwelve_widgets_init() {
213 214
 add_action( 'widgets_init', 'twentytwelve_widgets_init' );
214 215
 
215 216
 /**
216  
- * Count the number of footer sidebars to enable dynamic classes for the footer
  217
+ * Counts the number of footer sidebars to enable dynamic classes for the footer.
217 218
  *
218 219
  * @since Twenty Twelve 1.0
219 220
  */
@@ -228,7 +229,7 @@ function twentytwelve_homepage_sidebar_class() {
228 229
 
229 230
 if ( ! function_exists( 'twentytwelve_content_nav' ) ) :
230 231
 /**
231  
- * Display navigation to next/previous pages when applicable.
  232
+ * Displays navigation to next/previous pages when applicable.
232 233
  *
233 234
  * @since Twenty Twelve 1.0
234 235
  */
@@ -364,6 +365,9 @@ function twentytwelve_entry_meta() {
364 365
  * 3. White or empty background color to change the layout and spacing.
365 366
  *
366 367
  * @since Twenty Twelve 1.0
  368
+ *
  369
+ * @param array Existing class values.
  370
+ * @return array Filtered class values.
367 371
  */
368 372
 function twentytwelve_body_class( $classes ) {
369 373
 	$background_color = get_background_color();
@@ -384,8 +388,8 @@ function twentytwelve_body_class( $classes ) {
384 388
 add_filter( 'body_class', 'twentytwelve_body_class' );
385 389
 
386 390
 /**
387  
- * Adjust $content width for full-width and single image attachment templates
388  
- * and when there are no active widgets in the sidebar.
  391
+ * Adjusts content_width value for full-width and single image attachment
  392
+ * templates, and when there are no active widgets in the sidebar.
389 393
  *
390 394
  * @since Twenty Twelve 1.0
391 395
  */
17  wp-content/themes/twentytwelve/inc/custom-header.php
... ...
@@ -1,7 +1,7 @@
1 1
 <?php
2 2
 /**
3  
- * Implement an optional custom header for Twenty Twelve.
4  
- * http://codex.wordpress.org/Custom_Headers
  3
+ * Implements an optional custom header for Twenty Twelve.
  4
+ * See http://codex.wordpress.org/Custom_Headers
5 5
  *
6 6
  * @package WordPress
7 7
  * @subpackage Twenty_Twelve
@@ -9,12 +9,12 @@
9 9
  */
10 10
 
11 11
 /**
12  
- * Set up the WordPress core custom header arguments and settings.
13  
- * Use add_theme_support() to register support for 3.4 and up.
  12
+ * Sets up the WordPress core custom header arguments and settings.
14 13
  *
15  
- * @uses twentytwelve_header_style()
16  
- * @uses twentytwelve_admin_header_style()
17  
- * @uses twentytwelve_admin_header_image()
  14
+ * @uses add_theme_support() to register support for 3.4 and up.
  15
+ * @uses twentytwelve_header_style() to style front-end.
  16
+ * @uses twentytwelve_admin_header_style() to style wp-admin form.
  17
+ * @uses twentytwelve_admin_header_image() to add custom markup to wp-admin form.
18 18
  *
19 19
  * @since Twenty Twelve 1.0
20 20
  */
@@ -126,7 +126,8 @@ function twentytwelve_admin_header_style() {
126 126
 }
127 127
 
128 128
 /**
129  
- * Custom header image markup displayed on the Appearance > Header admin panel.
  129
+ * Outputs markup to be displayed on the Appearance > Header admin panel.
  130
+ * This callback overrides the default markup displayed there.
130 131
  *
131 132
  * @since Twenty Twelve 1.0
132 133
  */
16  wp-content/themes/twentytwelve/inc/theme-options.php
@@ -26,7 +26,7 @@ class Twenty_Twelve_Options {
26 26
 	public $options = array();
27 27
 
28 28
 	/**
29  
-	 * Constructor
  29
+	 * Constructor.
30 30
 	 *
31 31
 	 * @access public
32 32
 	 *
@@ -44,7 +44,7 @@ public function __construct() {
44 44
 	}
45 45
 
46 46
 	/**
47  
-	 * Register the form setting for our options array.
  47
+	 * Registers the form setting for our options array.
48 48
 	 *
49 49
 	 * This function is attached to the admin_init action hook.
50 50
 	 *
@@ -86,7 +86,7 @@ public function options_init() {
86 86
 	}
87 87
 
88 88
 	/**
89  
-	 * Add our theme options page to the admin menu.
  89
+	 * Adds our theme options page to the admin menu.
90 90
 	 *
91 91
 	 * This function is attached to the admin_menu action hook.
92 92
 	 *
@@ -148,7 +148,7 @@ public function settings_field_enable_fonts() {
148 148
 	}
149 149
 
150 150
 	/**
151  
-	 * Returns the options array.
  151
+	 * Displays the theme options page.
152 152
 	 *
153 153
 	 * @uses get_current_theme() for back compat, fallback for < 3.4
154 154
 	 * @access public
@@ -175,7 +175,7 @@ public function render_page() {
175 175
 	}
176 176
 
177 177
 	/**
178  
-	 * Sanitize and validate form input. Accepts an array, return a sanitized array.
  178
+	 * Sanitizes and validates form input.
179 179
 	 *
180 180
 	 * @see options_init()
181 181
 	 * @access public
@@ -195,7 +195,7 @@ public function validate( $input ) {
195 195
 	}
196 196
 
197 197
 	/**
198  
-	 * Implement Twenty Twelve theme options into Theme Customizer.
  198
+	 * Implements Twenty Twelve theme options into Theme Customizer.
199 199
 	 *
200 200
 	 * @since Twenty Twelve 1.0
201 201
 	 * @access public
@@ -233,7 +233,7 @@ public function customize_register( $wp_customize ) {
233 233
 	}
234 234
 
235 235
 	/**
236  
-	 * Bind JS handlers to make Theme Customizer preview reload changes asynchronously.
  236
+	 * Binds JS handlers to make Theme Customizer preview reload changes asynchronously.
237 237
 	 *
238 238
 	 * @since Twenty Twelve 1.0
239 239
 	 * @access public
@@ -249,7 +249,7 @@ public function customize_preview_js() {
249 249
 	}
250 250
 
251 251
 	/**
252  
-	 * Create path to load fonts CSS file with correct protocol.
  252
+	 * Creates path to load fonts CSS file with correct protocol.
253 253
 	 *
254 254
 	 * @since Twenty Twelve 1.0
255 255
 	 * @access public
7  wp-content/themes/twentytwelve/rtl.css
... ...
@@ -1,11 +1,10 @@
1 1
 /*
2 2
 Theme Name: Twenty Twelve
3  
-
4  
-Adding support for language written in a Right To Left (RTL) direction is easy -
5  
-it's just a matter of overwriting all the horizontal positioning attributes
  3
+Description: Adds support for languages written in a Right To Left (RTL) direction.
  4
+It's easy, just a matter of overwriting all the horizontal positioning attributes
6 5
 of your CSS stylesheet in a separate stylesheet file named rtl.css.
7 6
 
8  
-http://codex.wordpress.org/Right_to_Left_Language_Support
  7
+See http://codex.wordpress.org/Right_to_Left_Language_Support
9 8
 */
10 9
 
11 10
 
12  wp-content/themes/twentytwelve/sidebar-home.php
... ...
@@ -1,6 +1,6 @@
1 1
 <?php
2 2
 /**
3  
- * The Sidebar containing the homepage widget areas.
  3
+ * The sidebar containing the homepage widget areas.
4 4
  *
5 5
  * If no active widgets in either sidebar, they will be hidden completely.
6 6
  *
@@ -10,11 +10,11 @@
10 10
  */
11 11
 
12 12
 /*
13  
-The homepage widget area is triggered if any of the areas
14  
-have widgets. So let's check that first.
15  
-
16  
-If none of the sidebars have widgets, then let's bail early.
17  
-*/
  13
+ * The homepage widget area is triggered if any of the areas
  14
+ * have widgets. So let's check that first.
  15
+ *
  16
+ * If none of the sidebars have widgets, then let's bail early.
  17
+ */
18 18
 if ( ! is_active_sidebar( 2 ) && ! is_active_sidebar( 3 ) )
19 19
 	return;
20 20
 
4  wp-content/themes/twentytwelve/sidebar.php
... ...
@@ -1,8 +1,8 @@
1 1
 <?php
2 2
 /**
3  
- * The Sidebar containing the main widget area.
  3
+ * The sidebar containing the main widget area.
4 4
  *
5  
- * If no active widgets in sidebar, hide it completely.
  5
+ * If no active widgets in sidebar, let's hide it completely.
6 6
  *
7 7
  * @package WordPress
8 8
  * @subpackage Twenty_Twelve

0 notes on commit 3ec703a

Please sign in to comment.
Something went wrong with that request. Please try again.