Update the Customizer API inline docs.

props ericlewis.
fixes #27065.

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


git-svn-id: http://core.svn.wordpress.org/trunk@27246 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/customize.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Customize Controls
+ * Theme Customize Screen.
  *
  * @package WordPress
  * @subpackage Customize
@@ -9,7 +9,9 @@
 
 define( 'IFRAME_REQUEST', true );
 
+/** Load WordPress Administration Bootstrap */
 require_once( dirname( __FILE__ ) . '/admin.php' );
+
 if ( ! current_user_can( 'edit_theme_options' ) )
 	wp_die( __( 'Cheatin&#8217; uh?' ) );
 
@@ -199,6 +201,7 @@ do_action( 'customize_controls_print_scripts' );
 		'customize-login' => 1
 	), wp_login_url() );
 
+	// Prepare customizer settings to pass to Javascript.
 	$settings = array(
 		'theme'    => array(
 			'stylesheet' => $wp_customize->get_stylesheet(),
@@ -227,6 +230,7 @@ do_action( 'customize_controls_print_scripts' );
  		),
 	);
 
+	// Prepare Customize Setting objects to pass to Javascript.
 	foreach ( $wp_customize->settings() as $id => $setting ) {
 		$settings['settings'][ $id ] = array(
 			'value'     => $setting->js_value(),
@@ -234,6 +238,7 @@ do_action( 'customize_controls_print_scripts' );
 		);
 	}
 
+	// Prepare Customize Control objects to pass to Javascript.
 	foreach ( $wp_customize->controls() as $id => $control ) {
 		$control->to_json();
 		$settings['controls'][ $id ] = $control->json;

wp-includes/class-wp-customize-control.php

@@ -39,19 +39,19 @@ class WP_Customize_Control {
 	 * @access public
 	 * @var int
 	 */
-	public $priority          = 10;
+	public $priority = 10;
 
 	/**
 	 * @access public
 	 * @var string
 	 */
-	public $section           = '';
+	public $section = '';
 
 	/**
 	 * @access public
 	 * @var string
 	 */
-	public $label             = '';
+	public $label = '';
 
 	/**
 	 * @todo: Remove choices
@@ -59,7 +59,7 @@ class WP_Customize_Control {
 	 * @access public
 	 * @var array
 	 */
-	public $choices           = array();
+	public $choices = array();
 
 	/**
 	 * @access public
@@ -77,6 +77,8 @@ class WP_Customize_Control {
 	/**
 	 * Constructor.
 	 *
+	 * Supplied $args override class property defaults.
+	 *
 	 * If $args['settings'] is not defined, use the $id as the setting ID.
 	 *
 	 * @since 3.4.0
@@ -95,7 +97,6 @@ class WP_Customize_Control {
 		$this->manager = $manager;
 		$this->id = $id;
 
-
 		// Process settings.
 		if ( empty( $this->settings ) )
 			$this->settings = $id;
@@ -185,7 +186,7 @@ class WP_Customize_Control {
 	}
 
 	/**
-	 * Render the control. Renders the control wrapper, then calls $this->render_content().
+	 * Renders the control wrapper and calls $this->render_content() for the internals.
 	 *
 	 * @since 3.4.0
 	 */
@@ -199,7 +200,7 @@ class WP_Customize_Control {
 	}
 
 	/**
-	 * Get the data link parameter for a setting.
+	 * Get the data link attribute for a setting.
 	 *
 	 * @since 3.4.0
 	 *
@@ -214,7 +215,7 @@ class WP_Customize_Control {
 	}
 
 	/**
-	 * Render the data link parameter for a setting
+	 * Render the data link attribute for the control's input element.
 	 *
 	 * @since 3.4.0
 	 * @uses WP_Customize_Control::get_link()
@@ -228,7 +229,9 @@ class WP_Customize_Control {
 	/**
 	 * Render the control's content.
 	 *
-	 * Allows the content to be overriden without having to rewrite the wrapper.
+	 * Allows the content to be overriden without having to rewrite the wrapper in $this->render().
+	 *
+	 * Supports basic input types `text`, `checkbox`, `radio`, `select` and `dropdown-pages`.
 	 *
 	 * @since 3.4.0
 	 */
@@ -331,8 +334,6 @@ class WP_Customize_Color_Control extends WP_Customize_Control {
 	/**
 	 * Constructor.
 	 *
-	 * If $args['settings'] is not defined, use the $id as the setting ID.
-	 *
 	 * @since 3.4.0
 	 * @uses WP_Customize_Control::__construct()
 	 *
@@ -346,7 +347,7 @@ class WP_Customize_Color_Control extends WP_Customize_Control {
 	}
 
 	/**
-	 * Enqueue control related scripts/styles.
+	 * Enqueue scripts/styles for the color picker.
 	 *
 	 * @since 3.4.0
 	 */
@@ -467,8 +468,6 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 	/**
 	 * Constructor.
 	 *
-	 * If $args['settings'] is not defined, use the $id as the setting ID.
-	 *
 	 * @since 3.4.0
 	 * @uses WP_Customize_Upload_Control::__construct()
 	 *

wp-includes/class-wp-customize-manager.php

@@ -2,14 +2,39 @@
 /**
  * Customize Manager.
  *
+ * Bootstraps the Customize experience on the server-side.
+ *
+ * Sets up the theme-switching process if a theme other than the active one is
+ * being previewed and customized.
+ *
+ * Serves as a factory for Customize Controls and Settings, and
+ * instantiates default Customize Controls and Settings.
+ *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
 final class WP_Customize_Manager {
+	/**
+	 * An instance of the theme that is being customized.
+	 *
+	 * @var WP_Theme
+	 */
 	protected $theme;
+
+	/**
+	 * The directory name of the previously active theme (within the theme_root).
+	 *
+	 * @var string
+	 */
 	protected $original_stylesheet;
 
+	/**
+	 * Whether filters have been set to change the active theme to the theme being
+	 * customized.
+	 *
+	 * @var boolean
+	 */
 	protected $previewing = false;
 
 	protected $settings = array();
@@ -20,6 +45,11 @@ final class WP_Customize_Manager {
 
 	protected $customized;
 
+	/**
+	 * $_POST values for Customize Settings.
+	 *
+	 * @var array
+	 */
 	private $_post_values;
 
 	/**
@@ -127,17 +157,21 @@ final class WP_Customize_Manager {
 			// Once the theme is loaded, we'll validate it.
 			add_action( 'after_setup_theme', array( $this, 'after_setup_theme' ) );
 		} else {
+			// If the requested theme is not the active theme and the user doesn't have the
+			// switch_themes cap, bail.
 			if ( ! current_user_can( 'switch_themes' ) )
 				$this->wp_die( -1 );
 
-			// If the theme isn't active, you can't preview it if it is not allowed or has errors.
+			// If the theme has errors while loading, bail.
 			if ( $this->theme()->errors() )
 				$this->wp_die( -1 );
 
+			// If the theme isn't allowed per multisite settings, bail.
 			if ( ! $this->theme()->is_allowed() )
 				$this->wp_die( -1 );
 		}
 
+		// All good, let's do some internal business to preview the theme.
 		$this->start_previewing_theme();
 	}
 
@@ -154,9 +188,7 @@ final class WP_Customize_Manager {
 	}
 
 	/**
-	 * Start previewing the selected theme.
+	 * Start previewing the selected theme by adding filters to change the current theme.
-	 *
-	 * Adds filters to change the current theme.
 	 *
 	 * @since 3.4.0
 	 */
@@ -300,12 +332,12 @@ final class WP_Customize_Manager {
 	}
 
 	/**
-	 * Decode the $_POST attribute used to override the WP_Customize_Setting values.
+	 * Decode the $_POST['customized'] values for a specific Customize Setting.
 	 *
 	 * @since 3.4.0
 	 *
 	 * @param mixed $setting A WP_Customize_Setting derived object
-	 * @return string Sanitized attribute
+	 * @return string $post_value Sanitized value
 	 */
 	public function post_value( $setting ) {
 		if ( ! isset( $this->_post_values ) ) {
@@ -487,7 +519,7 @@ final class WP_Customize_Manager {
 	}
 
 	/**
-	 * Switch the theme and trigger the save action of each setting.
+	 * Switch the theme and trigger the save() method on each setting.
 	 *
 	 * @since 3.4.0
 	 */
@@ -522,9 +554,9 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the setting. Can be a
+	 * @param WP_Customize_Setting|string $id Customize Setting object, or ID.
-	 *                   theme mod or option name.
+	 * @param array $args                     Setting arguments; passed to WP_Customize_Setting
-	 * @param array $args Setting arguments.
+	 *                                        constructor.
 	 */
 	public function add_setting( $id, $args = array() ) {
 		if ( is_a( $id, 'WP_Customize_Setting' ) )
@@ -540,8 +572,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the setting.
+	 * @param string $id Customize Setting ID.
-	 * @return object The settings object.
+	 * @return WP_Customize_Setting
 	 */
 	public function get_setting( $id ) {
 		if ( isset( $this->settings[ $id ] ) )
@@ -553,7 +585,7 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the setting.
+	 * @param string $id Customize Setting ID.
 	 */
 	public function remove_setting( $id ) {
 		unset( $this->settings[ $id ] );
@@ -564,8 +596,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the section.
+	 * @param WP_Customize_Section|string $id   Customize Section object, or Section ID.
-	 * @param array $args Section arguments.
+	 * @param array                       $args Section arguments.
 	 */
 	public function add_section( $id, $args = array() ) {
 		if ( is_a( $id, 'WP_Customize_Section' ) )
@@ -581,8 +613,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the section.
+	 * @param string $id Section ID.
-	 * @return object The section object.
+	 * @return WP_Customize_Section
 	 */
 	public function get_section( $id ) {
 		if ( isset( $this->sections[ $id ] ) )
@@ -594,7 +626,7 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the section.
+	 * @param string $id Section ID.
 	 */
 	public function remove_section( $id ) {
 		unset( $this->sections[ $id ] );
@@ -605,8 +637,9 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the control.
+	 * @param WP_Customize_Control|string $id   Customize Control object, or ID.
-	 * @param array $args Setting arguments.
+	 * @param array                       $args Control arguments; passed to WP_Customize_Control
+	 *                                          constructor.
 	 */
 	public function add_control( $id, $args = array() ) {
 		if ( is_a( $id, 'WP_Customize_Control' ) )
@@ -622,8 +655,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the control.
+	 * @param string $id ID of the control.
-	 * @return object The settings object.
+	 * @return WP_Customize_Control $control The control object.
 	 */
 	public function get_control( $id ) {
 		if ( isset( $this->controls[ $id ] ) )
@@ -631,11 +664,11 @@ final class WP_Customize_Manager {
 	}
 
 	/**
-	 * Remove a customize setting.
+	 * Remove a customize control.
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $id A specific ID of the control.
+	 * @param string $id ID of the control.
 	 */
 	public function remove_control( $id ) {
 		unset( $this->controls[ $id ] );
@@ -662,11 +695,13 @@ final class WP_Customize_Manager {
 	/**
 	 * Prepare settings and sections.
 	 *
+	 * For each, check if required related components exist,
+	 * whether the user has the necessary capabilities,
+	 * and sort by priority.
+	 *
 	 * @since 3.4.0
 	 */
 	public function prepare_controls() {
-		// Prepare controls
-		// Reversing makes uasort sort by time added when conflicts occur.
 
 		$this->controls = array_reverse( $this->controls );
 		$controls = array();
@@ -680,7 +715,8 @@ final class WP_Customize_Manager {
 		}
 		$this->controls = $controls;
 
-		// Prepare sections
+		// Prepare sections.
+		// Reversing makes uasort sort by time added when conflicts occur.
 		$this->sections = array_reverse( $this->sections );
 		uasort( $this->sections, array( $this, '_cmp_priority' ) );
 		$sections = array();
@@ -995,10 +1031,10 @@ final class WP_Customize_Manager {
 };
 
 /**
- * Validates a hex color.
+ * Sanitizes a hex color.
  *
  * Returns either '', a 3 or 6 digit hex color (with #), or null.
- * For validating values without a #, see sanitize_hex_color_no_hash().
+ * For sanitizing values without a #, see sanitize_hex_color_no_hash().
  *
  * @since 3.4.0
  *

wp-includes/class-wp-customize-section.php

@@ -2,28 +2,67 @@
 /**
  * Customize Section Class.
  *
+ * A UI container for controls, managed by the WP_Customize_Manager.
+ *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
 class WP_Customize_Section {
+	/**
+	 * @access public
+	 *
+	 * @var WP_Customize_Manager
+	 */
 	public $manager;
+
+	/**
+	 * Unique identifier.
+	 *
+	 * @var string
+	 */
 	public $id;
+
+	/**
+	 * Priority of the section which informs load order of sections.
+	 *
+	 * @var integer
+	 */
 	public $priority       = 10;
+
+	/**
+	 * Capability required for the section.
+	 *
+	 * @var string
+	 */
 	public $capability     = 'edit_theme_options';
 	public $theme_supports = '';
+
+	/**
+	 * Title of the section to show in UI.
+	 *
+	 * @var string
+	 */
 	public $title          = '';
+
+	/**
+	 * Description to show in the UI.
+	 *
+	 * @var string
+	 */
 	public $description    = '';
 	public $controls;
 
 	/**
 	 * Constructor.
 	 *
+	 * Any supplied $args override class property defaults.
+	 *
 	 * @since 3.4.0
 	 *
 	 * @param WP_Customize_Manager $manager
-	 * @param string $id An specific ID of the section.
+	 * @param string               $id      An specific ID of the section.
-	 * @param array $args Section arguments.
+	 * @param array                $args    Section arguments.
 	 */
 	function __construct( $manager, $id, $args = array() ) {
 		$keys = array_keys( get_class_vars( __CLASS__ ) );
@@ -41,7 +80,8 @@ class WP_Customize_Section {
 	}
 
 	/**
-	 * Check if the theme supports the section and check user capabilities.
+	 * Checks required user capabilities and whether the theme has the
+	 * feature support required by the section.
 	 *
 	 * @since 3.4.0
 	 *
@@ -71,7 +111,7 @@ class WP_Customize_Section {
 		 *
 		 * @since 3.4.0
 		 *
-		 * @param WP_Customize_Section $this The WP_Customize_Section instance.
+		 * @param WP_Customize_Section $this WP_Customize_Section instance.
 		 */
 		do_action( 'customize_render_section', $this );
 		/**
@@ -88,7 +128,7 @@ class WP_Customize_Section {
 	}
 
 	/**
-	 * Render the section.
+	 * Render the section, and the controls that have been added to it.
 	 *
 	 * @since 3.4.0
 	 */

wp-includes/class-wp-customize-setting.php

@@ -2,36 +2,78 @@
 /**
  * Customize Setting Class.
  *
+ * Handles saving and sanitizing of settings.
+ *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
 class WP_Customize_Setting {
+	/**
+	 * @access public
+	 * @var WP_Customize_Manager
+	 */
 	public $manager;
+
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $id;
 
-	public $type            = 'theme_mod';
+	/**
-	public $capability      = 'edit_theme_options';
+	 * @access public
+	 * @var string
+	 */
+	public $type = 'theme_mod';
+
+	/**
+	 * Capability required to edit this setting.
+	 *
+	 * @var string
+	 */
+	public $capability = 'edit_theme_options';
+
+	/**
+	 * Feature a theme is required to support to enable this setting.
+	 *
+	 * @access public
+	 * @var string
+	 */
 	public $theme_supports  = '';
 	public $default         = '';
 	public $transport       = 'refresh';
 
+	/**
+	 * Server-side sanitization callback for the setting's value.
+	 *
+	 * @var callback
+	 */
 	public $sanitize_callback    = '';
 	public $sanitize_js_callback = '';
 
 	protected $id_data = array();
-	private $_post_value; // Cached, sanitized $_POST value.
+
+	/**
+	 * Cached and sanitized $_POST value for the setting.
+	 *
+	 * @access private
+	 * @var mixed
+	 */
+	private $_post_value;
 
 	/**
 	 * Constructor.
 	 *
+	 * Any supplied $args override class property defaults.
+	 *
 	 * @since 3.4.0
 	 *
 	 * @param WP_Customize_Manager $manager
-	 * @param string $id An specific ID of the setting. Can be a
+	 * @param string               $id      An specific ID of the setting. Can be a
-	 *                   theme mod or option name.
+	 *                                      theme mod or option name.
-	 * @param array $args Setting arguments.
+	 * @param array                $args    Setting arguments.
-	 * @return WP_Customize_Setting
+	 * @return WP_Customize_Setting $setting
 	 */
 	function __construct( $manager, $id, $args = array() ) {
 		$keys = array_keys( get_class_vars( __CLASS__ ) );
@@ -98,7 +140,8 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Set the value of the parameter for a specific theme.
+	 * Check user capabilities and theme supports, and then save
+	 * the value of the setting.
 	 *
 	 * @since 3.4.0
 	 *
@@ -116,7 +159,7 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Fetches, validates, and sanitizes the $_POST value.
+	 * Fetch and sanitize the $_POST value for the setting.
 	 *
 	 * @since 3.4.0
 	 *
@@ -124,9 +167,11 @@ class WP_Customize_Setting {
 	 * @return mixed The default value on failure, otherwise the sanitized value.
 	 */
 	public final function post_value( $default = null ) {
+		// Check for a cached value
 		if ( isset( $this->_post_value ) )
 			return $this->_post_value;
 
+		// Call the manager for the post value
 		$result = $this->manager->post_value( $this );
 
 		if ( isset( $result ) )
@@ -149,7 +194,7 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Set the value of the parameter for a specific theme.
+	 * Save the value of the setting, using the related API.
 	 *
 	 * @since 3.4.0
 	 *
@@ -190,7 +235,7 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Update the theme mod from the value of the parameter.
+	 * Update the option from the value of the setting.
 	 *
 	 * @since 3.4.0
 	 *
@@ -210,13 +255,14 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Fetch the value of the parameter for a specific theme.
+	 * Fetch the value of the setting.
 	 *
 	 * @since 3.4.0
 	 *
-	 * @return mixed The requested value.
+	 * @return mixed The value.
 	 */
 	public function value() {
+		// Get the callback that corresponds to the setting type.
 		switch( $this->type ) {
 			case 'theme_mod' :
 				$function = 'get_theme_mod';
@@ -238,7 +284,7 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Escape the parameter's value for use in JavaScript.
+	 * Sanitize the setting's value for use in JavaScript.
 	 *
 	 * @since 3.4.0
 	 *
@@ -254,7 +300,7 @@ class WP_Customize_Setting {
 	}
 
 	/**
-	 * Check if the theme supports the setting and check user capabilities.
+	 * Validate user capabilities whether the theme supports the setting.
 	 *
 	 * @since 3.4.0
 	 *