phpdoc for Customizer classes and methods. Props bananastalktome. see #21303

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

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

@@ -6,25 +6,71 @@
  * @subpackage Customize
  * @since 3.4.0
  */
-
 class WP_Customize_Control {
+	/**
+	 * @access public
+	 * @var WP_Customize_Manager
+	 */
 	public $manager;
+	
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $id;
 
-	// All settings tied to the control.
+	/**
+	 * All settings tied to the control.
+	 *
+	 * @access public
+	 * @var array
+	 */
 	public $settings;
 
-	// The primary setting for the control (if there is one).
+	/**
+	 * The primary setting for the control (if there is one).
+	 *
+	 * @access public
+	 * @var string
+	 */
 	public $setting = 'default';
 
+	/**
+	 * @access public
+	 * @var int
+	 */
 	public $priority          = 10;
+	
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $section           = '';
+	
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $label             = '';
-	// @todo: remove choices
+	
+	/**
+	 * @todo: Remove choices
+	 *
+	 * @access public
+	 * @var array
+	 */
 	public $choices           = array();
 
+	/**
+	 * @access public
+	 * @var array
+	 */
 	public $json = array();
 
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $type = 'text';
 
 
@@ -34,6 +80,10 @@ class WP_Customize_Control {
 	 * If $args['settings'] is not defined, use the $id as the setting ID.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param WP_Customize_Manager $manager
+	 * @param string $id
+	 * @param array $args
 	 */
 	function __construct( $manager, $id, $args = array() ) {
 		$keys = array_keys( get_object_vars( $this ) );
@@ -75,6 +125,9 @@ class WP_Customize_Control {
 	 * Grabs the main setting by default.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param string $setting_key
+	 * @return mixed The requested setting's value, if the setting exists.
 	 */
 	public final function value( $setting_key = 'default' ) {
 		if ( isset( $this->settings[ $setting_key ] ) )
@@ -119,6 +172,7 @@ class WP_Customize_Control {
 	 * Check capabilities and render the control.
 	 *
 	 * @since 3.4.0
+	 * @uses WP_Customize_Control::render()
 	 */
 	public final function maybe_render() {
 		if ( ! $this->check_capabilities() )
@@ -144,6 +198,14 @@ class WP_Customize_Control {
 		</li><?php
 	}
 	
+	/**
+	 * Get the data link parameter for a setting.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @param string $setting_key
+	 * @return string Data link parameter, if $setting_key is a valid setting, empty string otherwise.
+	 */
 	public function get_link( $setting_key = 'default' ) {
 		if ( ! isset( $this->settings[ $setting_key ] ) )
 			return '';
@@ -151,6 +213,14 @@ class WP_Customize_Control {
 		return 'data-customize-setting-link="' . esc_attr( $this->settings[ $setting_key ]->id ) . '"';
 	}
 	
+	/**
+	 * Render the data link parameter for a setting
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Control::get_link()
+	 *
+	 * @param string $setting_key
+	 */
 	public function link( $setting_key = 'default' ) {
 		echo $this->get_link( $setting_key );
 	}
@@ -238,25 +308,69 @@ class WP_Customize_Control {
 	}
 }
 
+/**
+ * Customize Color Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Color_Control extends WP_Customize_Control {
+	/**
+	 * @access public
+	 * @var string
+	 */
 	public $type = 'color';
+	
+	/**
+	 * @access public
+	 * @var array
+	 */
 	public $statuses;
 
+	/**
+	 * Constructor.
+	 *
+	 * If $args['settings'] is not defined, use the $id as the setting ID.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Control::__construct()
+	 *
+	 * @param WP_Customize_Manager $manager
+	 * @param string $id
+	 * @param array $args
+	 */
 	public function __construct( $manager, $id, $args = array() ) {
 		$this->statuses = array( '' => __('Default') );
 		parent::__construct( $manager, $id, $args );
 	}
 
+	/**
+	 * Enqueue control related scripts/styles.
+	 *
+	 * @since 3.4.0
+	 */
 	public function enqueue() {
 		wp_enqueue_script( 'farbtastic' );
 		wp_enqueue_style( 'farbtastic' );
 	}
 
+	/**
+	 * Refresh the parameters passed to the JavaScript via JSON.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Control::to_json()
+	 */
 	public function to_json() {
 		parent::to_json();
 		$this->json['statuses'] = $this->statuses;
 	}
 
+	/**
+	 * Render the control's content.
+	 *
+	 * @since 3.4.0
+	 */
 	public function render_content() {
 		?>
 		<label>
@@ -276,15 +390,33 @@ class WP_Customize_Color_Control extends WP_Customize_Control {
 	}
 }
 
+/**
+ * Customize Upload Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Upload_Control extends WP_Customize_Control {
 	public $type    = 'upload';
 	public $removed = '';
 	public $context;
 
+	/**
+	 * Enqueue control related scripts/styles.
+	 *
+	 * @since 3.4.0
+	 */
 	public function enqueue() {
 		wp_enqueue_script( 'wp-plupload' );
 	}
 	
+	/**
+	 * Refresh the parameters passed to the JavaScript via JSON.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Control::to_json()
+	 */
 	public function to_json() {
 		parent::to_json();
 
@@ -294,6 +426,11 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
 			$this->json['context'] = $this->context;
 	}
 
+	/**
+	 * Render the control's content.
+	 *
+	 * @since 3.4.0
+	 */
 	public function render_content() {
 		?>
 		<label>
@@ -307,6 +444,13 @@ class WP_Customize_Upload_Control extends WP_Customize_Control {
 	}
 }
 
+/**
+ * Customize Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 	public $type = 'image';
 	public $get_url;
@@ -314,6 +458,18 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 
 	protected $tabs = array();
 
+	/**
+	 * Constructor.
+	 *
+	 * If $args['settings'] is not defined, use the $id as the setting ID.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Upload_Control::__construct()
+	 *
+	 * @param WP_Customize_Manager $manager
+	 * @param string $id
+	 * @param array $args
+	 */
 	public function __construct( $manager, $id, $args ) {
 		$this->statuses = array( '' => __('No Image') );
 
@@ -323,11 +479,22 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 		$this->add_tab( 'uploaded',   __('Uploaded'),   array( $this, 'tab_uploaded' ) );
 	}
 
+	/**
+	 * Refresh the parameters passed to the JavaScript via JSON.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Upload_Control::to_json()
+	 */
 	public function to_json() {
 		parent::to_json();
 		$this->json['statuses'] = $this->statuses;
 	}
 
+	/**
+	 * Render the control's content.
+	 *
+	 * @since 3.4.0
+	 */
 	public function render_content() {
 		$src = $this->value();
 		if ( isset( $this->get_url ) )
@@ -373,6 +540,15 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 		<?php
 	}
 	
+	/**
+	 * Add a tab to the control.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @param string $id
+	 * @param string $label
+	 * @param mixed $callback
+	 */
 	public function add_tab( $id, $label, $callback ) {
 		$this->tabs[ $id ] = array(
 			'label'    => $label,
@@ -380,10 +556,20 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 		);
 	}
 
+	/**
+	 * Remove a tab from the control.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @param string $id
+	 */
 	public function remove_tab( $id ) {
 		unset( $this->tabs[ $id ] );
 	}
 
+	/**
+	 * @since 3.4.0
+	 */
 	public function tab_upload_new() {
 		if ( ! _device_can_upload() ) {
 			?>
@@ -401,12 +587,21 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 		}
 	}
 	
+	/**
+	 * @since 3.4.0
+	 */
 	public function tab_uploaded() {
 		?>
 		<div class="uploaded-target"></div>
 		<?php
 	}
 
+	/**
+	 * @since 3.4.0
+	 *
+	 * @param string $url
+	 * @param string $thumbnail_url
+	 */
 	public function print_tab_image( $url, $thumbnail_url = null ) {
 		$url = set_url_scheme( $url );
 		$thumbnail_url = ( $thumbnail_url ) ? set_url_scheme( $thumbnail_url ) : $url;
@@ -418,7 +613,23 @@ class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
 	}
 }
 
+/**
+ * Customize Background Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Image_Control::__construct()
+	 *
+	 * @param WP_Customize_Manager $manager
+	 */
 	public function __construct( $manager ) {
 		parent::__construct( $manager, 'background_image', array(
 			'label'    => __( 'Background Image' ),
@@ -431,6 +642,9 @@ class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
 			$this->add_tab( 'default',  __('Default'),  array( $this, 'tab_default_background' ) );
 	}
 
+	/**
+	 * @since 3.4.0
+	 */
 	public function tab_uploaded() {
 		$backgrounds = get_posts( array(
 			'post_type'  => 'attachment',
@@ -449,12 +663,33 @@ class WP_Customize_Background_Image_Control extends WP_Customize_Image_Control {
 			$this->print_tab_image( esc_url_raw( $background->guid ) );
 	}
 	
+	/**
+	 * @since 3.4.0
+	 * @uses WP_Customize_Image_Control::print_tab_image()
+	 */
 	public function tab_default_background() {
 		$this->print_tab_image( $this->setting->default );
 	}
 }
 
+/**
+ * Customize Header Image Control Class
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 3.4.0
+	 * @uses WP_Customize_Image_Control::__construct()
+	 * @uses WP_Customize_Image_Control::add_tab()
+	 *
+	 * @param WP_Customize_Manager $manager
+	 */
 	public function __construct( $manager ) {
 		parent::__construct( $manager, 'header_image', array(
 			'label'    => __( 'Header Image' ),
@@ -477,6 +712,12 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
 		$this->add_tab( 'default',  __('Default'),  array( $this, 'tab_default_headers' ) );
 	}
 
+	/**
+	 * @since 3.4.0
+	 *
+	 * @param mixed $choice Which header image to select. (@see Custom_Image_Header::get_header_image() )
+	 * @param array $header
+	 */
 	public function print_header_image( $choice, $header ) {
 		$header['url']           = set_url_scheme( $header['url'] );
 		$header['thumbnail_url'] = set_url_scheme( $header['thumbnail_url'] );
@@ -497,6 +738,9 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
 		<?php
 	}
 	
+	/**
+	 * @since 3.4.0
+	 */
 	public function tab_uploaded() {
 		$headers = get_uploaded_header_images();
 
@@ -506,6 +750,9 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
 			$this->print_header_image( $choice, $header );
 	}
 
+	/**
+	 * @since 3.4.0
+	 */
 	public function tab_default_headers() {
 		global $custom_image_header;
 		$custom_image_header->process_default_headers();

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

@@ -1,12 +1,11 @@
 <?php
 /**
- * Customize
+ * Customize Manager.
  *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
-
 final class WP_Customize_Manager {
 	protected $theme;
 	protected $original_stylesheet;
@@ -60,6 +59,8 @@ final class WP_Customize_Manager {
 	 * Return true if it's an AJAX request.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @return bool
 	 */
 	public function doing_ajax() {
 		return isset( $_POST['customized'] ) || ( defined( 'DOING_AJAX' ) && DOING_AJAX );
@@ -69,10 +70,10 @@ final class WP_Customize_Manager {
 	 * Custom wp_die wrapper. Returns either the standard message for UI
 	 * or the AJAX message.
 	 *
+	 * @since 3.4.0
+	 *
 	 * @param mixed $ajax_message AJAX return
 	 * @param mixed $message UI message 
-	 *
-	 * @since 3.4.0
 	 */
 	protected function wp_die( $ajax_message, $message = null ) {
 		if ( $this->doing_ajax() )
@@ -88,6 +89,8 @@ final class WP_Customize_Manager {
 	 * Return the AJAX wp_die() handler if it's a customized request.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @return string
 	 */
 	public function wp_die_handler() {
 		if ( $this->doing_ajax() )
@@ -95,6 +98,7 @@ final class WP_Customize_Manager {
 
 		return '_default_wp_die_handler';
 	}
+	
 	/**
 	 * Start preview and customize theme.
 	 *
@@ -137,6 +141,11 @@ final class WP_Customize_Manager {
 		$this->start_previewing_theme();
 	}
 	
+	/**
+	 * Callback to validate a theme once it is loaded
+	 *
+	 * @since 3.4.0
+	 */
 	function after_setup_theme() {
 		if ( ! $this->doing_ajax() && ! validate_current_theme() ) {
 			wp_redirect( 'themes.php?broken=true' );
@@ -279,6 +288,9 @@ final class WP_Customize_Manager {
 	 * Instead, the JS will sniff out the location header.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param $status
+	 * @return int
 	 */
 	public function wp_redirect_status( $status ) {
 		if ( $this->is_preview() && ! is_admin() )
@@ -291,6 +303,9 @@ final class WP_Customize_Manager {
 	 * Decode the $_POST attribute used to override the WP_Customize_Setting values.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param mixed $setting A WP_Customize_Setting derived object
+	 * @return string Sanitized attribute
 	 */
 	public function post_value( $setting ) {
 		if ( ! isset( $this->_post_values ) ) {
@@ -464,6 +479,7 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
+	 * @param $current_theme {@internal Parameter is not used}
 	 * @return string Theme name.
 	 */
 	public function current_theme( $current_theme ) {
@@ -630,6 +646,7 @@ final class WP_Customize_Manager {
 	 *
 	 * @param object $a Object A.
 	 * @param object $b Object B.
+	 * @return int
 	 */
 	protected final function _cmp_priority( $a, $b ) {
 		$ap = $a->priority;
@@ -960,6 +977,9 @@ final class WP_Customize_Manager {
 	 * Accepts 'blank', and otherwise uses sanitize_hex_color_no_hash().
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param string $color
+	 * @return string
 	 */
 	public function _sanitize_header_textcolor( $color ) {
 		return ( 'blank' === $color ) ? 'blank' : sanitize_hex_color_no_hash( $color );
@@ -973,6 +993,9 @@ final class WP_Customize_Manager {
  * For validating values without a #, see sanitize_hex_color_no_hash().
  *
  * @since 3.4.0
+ *
+ * @param string $color
+ * @return string|null
  */
 function sanitize_hex_color( $color ) {
 	if ( '' === $color )
@@ -995,6 +1018,10 @@ function sanitize_hex_color( $color ) {
  * Returns either '', a 3 or 6 digit hex color (without a #), or null.
  *
  * @since 3.4.0
+ * @uses sanitize_hex_color()
+ *
+ * @param string $color
+ * @return string|null
  */
 function sanitize_hex_color_no_hash( $color ) {
 	$color = ltrim( $color, '#' );
@@ -1012,6 +1039,9 @@ function sanitize_hex_color_no_hash( $color ) {
  * This method should only be necessary if using sanitize_hex_color_no_hash().
  *
  * @since 3.4.0
+ *
+ * @param string $color
+ * @return string
  */
 function maybe_hash_hex_color( $color ) {
 	if ( $unhashed = sanitize_hex_color_no_hash( $color ) )

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

@@ -1,12 +1,11 @@
 <?php
 /**
- * Customize Section Class
+ * Customize Section Class.
  *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
-
 class WP_Customize_Section {
 	public $manager;
 	public $id;
@@ -22,6 +21,7 @@ class WP_Customize_Section {
 	 *
 	 * @since 3.4.0
 	 *
+	 * @param WP_Customize_Manager $manager
 	 * @param string $id An specific ID of the section.
 	 * @param array $args Section arguments.
 	 */
@@ -72,7 +72,6 @@ class WP_Customize_Section {
 		$this->render();
 	}
 
-
 	/**
 	 * Render the section.
 	 *

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

@@ -1,12 +1,11 @@
 <?php
 /**
- * Customize Setting Class
+ * Customize Setting Class.
  *
  * @package WordPress
  * @subpackage Customize
  * @since 3.4.0
  */
-
 class WP_Customize_Setting {
 	public $manager;
 	public $id;
@@ -28,9 +27,11 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
+	 * @param WP_Customize_Manager $manager
 	 * @param string $id An specific ID of the setting. Can be a
 	 *                   theme mod or option name.
 	 * @param array $args Setting arguments.
+	 * @return WP_Customize_Setting
 	 */
 	function __construct( $manager, $id, $args = array() ) {
 		$keys = array_keys( get_class_vars( __CLASS__ ) );
@@ -87,8 +88,9 @@ class WP_Customize_Setting {
 	 * Callback function to filter the theme mods and options.
 	 *
 	 * @since 3.4.0
+	 * @uses WP_Customize_Setting::multidimensional_replace()
 	 *
-	 * @param mixed Old value.
+	 * @param mixed $original Old value.
 	 * @return mixed New or old value.
 	 */
 	public function _preview_filter( $original ) {
@@ -118,8 +120,8 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param $default mixed A default value which is used as a fallback. Default is null.
+	 * @param mixed $default A default value which is used as a fallback. Default is null.
-	 * @return mixed Either the default value on failure or sanitized value.
+	 * @return mixed The default value on failure, otherwise the sanitized value.
 	 */
 	public final function post_value( $default = null ) {
 		if ( isset( $this->_post_value ) )
@@ -138,7 +140,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param $value mixed The value to sanitize.
+	 * @param mixed $value The value to sanitize.
 	 * @return mixed Null if an input isn't valid, otherwise the sanitized value.
 	 */
 	public function sanitize( $value ) {
@@ -151,7 +153,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param $value mixed The value to update.
+	 * @param mixed $value The value to update.
 	 * @return mixed The result of saving the value.
 	 */
 	protected function update( $value ) {
@@ -172,7 +174,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param $value mixed The value to update.
+	 * @param mixed $value The value to update.
 	 * @return mixed The result of saving the value.
 	 */
 	protected function _update_theme_mod( $value ) {
@@ -192,7 +194,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param $value mixed The value to update.
+	 * @param mixed $value The value to update.
 	 * @return mixed The result of saving the value.
 	 */
 	protected function _update_option( $value ) {
@@ -276,7 +278,7 @@ class WP_Customize_Setting {
 	 * @param $root
 	 * @param $keys
 	 * @param bool $create Default is false.
-	 * @return null|array
+	 * @return null|array Keys are 'root', 'node', and 'key'.
 	 */
 	final protected function multidimensional( &$root, $keys, $create = false ) {
 		if ( $create && empty( $root ) )
@@ -372,8 +374,16 @@ class WP_Customize_Setting {
  * A setting that is used to filter a value, but will not save the results.
  *
  * Results should be properly handled using another setting or callback.
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
  */
 class WP_Customize_Filter_Setting extends WP_Customize_Setting {
+	
+	/**
+	 * @since 3.4.0
+	 */
 	public function update() {}
 }
 
@@ -381,10 +391,19 @@ class WP_Customize_Filter_Setting extends WP_Customize_Setting {
  * A setting that is used to filter a value, but will not save the results.
  *
  * Results should be properly handled using another setting or callback.
+ *
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
  */
 final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
 	public $id = 'header_image_data';
 
+	/**
+	 * @since 3.4.0
+	 *
+	 * @param $value
+	 */
 	public function update( $value ) {
 		global $custom_image_header;
 
@@ -400,9 +419,20 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
 	}
 }
 
+/**
+ * @package WordPress
+ * @subpackage Customize
+ * @since 3.4.0
+ */
 final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
 	public $id = 'background_image_thumb';
 
+	/**
+	 * @since 3.4.0
+	 * @uses remove_theme_mod()
+	 *
+	 * @param $value
+	 */
 	public function update( $value ) {
 		remove_theme_mod( 'background_image_thumb' );
 	}