<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27903] trunk/src/wp-includes/class-wp-customize-widgets.php: Second-pass inline documentation improvements for WP_Customize_Widgets.</title>
</head>
<body>

<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt;  }
#msg dl a { font-weight: bold}
#msg dl a:link    { color:#fc3; }
#msg dl a:active  { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff  {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27903">27903</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-04-02 05:44:54 +0000 (Wed, 02 Apr 2014)</dd>
</dl>

<h3>Log Message</h3>
<pre>Second-pass inline documentation improvements for WP_Customize_Widgets.

See <a href="http://core.trac.wordpress.org/ticket/27534">#27534</a>.</pre>

<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesclasswpcustomizewidgetsphp">trunk/src/wp-includes/class-wp-customize-widgets.php</a></li>
</ul>

</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesclasswpcustomizewidgetsphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-wp-customize-widgets.php (27902 => 27903)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-wp-customize-widgets.php     2014-04-02 03:01:31 UTC (rev 27902)
+++ trunk/src/wp-includes/class-wp-customize-widgets.php        2014-04-02 05:44:54 UTC (rev 27903)
</span><span class="lines">@@ -9,14 +9,18 @@
</span><span class="cx">  * @since 3.9.0
</span><span class="cx">  */
</span><span class="cx"> final class WP_Customize_Widgets {
</span><ins>+
</ins><span class="cx">   /**
</span><ins>+        * WP_Customize_Manager instance.
+        *
+        * @since 3.9.0
</ins><span class="cx">    * @access public
</span><span class="cx">   * @var WP_Customize_Manager
</span><span class="cx">   */
</span><span class="cx">  public $manager;
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * All id_bases for widgets defined in core
</del><ins>+         * All id_bases for widgets defined in core.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access protected
</span><span class="lines">@@ -71,6 +75,8 @@
</span><span class="cx">   *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><ins>+        *
+        * @param WP_Customize_Manager $manager Customize manager bootstrap instance.
</ins><span class="cx">    */
</span><span class="cx">  public function __construct( WP_Customize_Manager $manager ) {
</span><span class="cx">          $this->manager = $manager;
</span><span class="lines">@@ -107,15 +113,16 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * Set up widget addition previews.
</ins><span class="cx">    *
</span><ins>+        * Since the widgets get registered on 'widgets_init' before the customizer
+        * settings are set up on 'customize_register', we have to filter the options
+        * similarly to how the setting previewer will filter the options later.
</ins><span class="cx">    *
</span><del>-        * Since the widgets get registered (widgets_init) before the customizer settings are set up (customize_register),
-        * we have to filter the options similarly to how the setting previewer will filter the options later.
-        *
</del><span class="cx">    * @since 3.9.0
</span><span class="cx">   *
</span><span class="cx">   * @access public
</span><del>-        * @global WP_Customize_Manager $wp_customize
</del><ins>+         * @global WP_Customize_Manager $wp_customize Customizer instance.
</ins><span class="cx">    */
</span><span class="cx">  public function setup_widget_addition_previews() {
</span><span class="cx">          $is_customize_preview = false;
</span><span class="lines">@@ -168,15 +175,20 @@
</span><span class="cx"> 
</span><span class="cx">          foreach ( $customized as $setting_id => $value ) {
</span><span class="cx">                  if ( preg_match( '/^(widget_.+?)(\[(\d+)\])?$/', $setting_id, $matches ) ) {
</span><ins>+
+                               /*
+                                * @todo Replace the next two lines with the following once WordPress supports PHP 5.3.
+                                *
+                                * $self = $this; // not needed in PHP 5.4
+                                *
+                                * $function = function ( $value ) use ( $self, $setting_id ) {
+                                *              return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
+                                * };
+                                */
</ins><span class="cx">                           $body     = sprintf( 'global $wp_customize; return $wp_customize->widgets->prepreview_added_widget_instance( $value, %s );', var_export( $setting_id, true ) );
</span><span class="cx">                          $function = create_function( '$value', $body );
</span><del>-                               // @todo replace above two lines with following once PHP 5.3 happens in WordPress
-                               // $self = $this; // not needed in PHP 5.4
-                               // $function = function ( $value ) use ( $self, $setting_id ) {
-                               //      return $self->manager->widgets->prepreview_added_widget_instance( $value, $setting_id );
-                               //};
</del><span class="cx"> 
</span><del>-                               $option   = $matches[1];
</del><ins>+                                $option = $matches[1];
</ins><span class="cx"> 
</span><span class="cx">                          $hook = sprintf( 'option_%s', $option );
</span><span class="cx">                          add_filter( $hook, $function );
</span><span class="lines">@@ -186,9 +198,10 @@
</span><span class="cx">                          add_filter( $hook, $function );
</span><span class="cx">                          $this->_prepreview_added_filters[] = compact( 'hook', 'function' );
</span><span class="cx"> 
</span><del>-                               /**
-                                * Make sure the option is registered so that the update_option won't fail due to
-                                * the filters providing a default value, which causes the update_option() to get confused.
</del><ins>+                                /*
+                                * Make sure the option is registered so that the update_option()
+                                * won't fail due to the filters providing a default value, which
+                                * causes the update_option() to get confused.
</ins><span class="cx">                            */
</span><span class="cx">                          add_option( $option, array() );
</span><span class="cx">                  }
</span><span class="lines">@@ -198,17 +211,17 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * Ensure that newly-added widgets will appear in the widgets_sidebars.
</ins><span class="cx">    *
</span><ins>+        * This is necessary because the customizer's setting preview filters
+        * are added after the widgets_init action, which is too late for the
+        * widgets to be set up properly.
</ins><span class="cx">    *
</span><del>-        * Ensure that newly-added widgets will appear in the widgets_sidebars.
-        * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
-        * which is too late for the widgets to be set up properly.
-        *
</del><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><del>-        * @param array $sidebars_widgets Array of
-        * @return array
</del><ins>+         * @param array $sidebars_widgets Associative array of sidebars and their widgets.
+        * @return array Filtered array of sidebars and their widgets.
</ins><span class="cx">    */
</span><span class="cx">  public function prepreview_added_sidebars_widgets( $sidebars_widgets ) {
</span><span class="cx">          foreach ( $this->_customized as $setting_id => $value ) {
</span><span class="lines">@@ -221,12 +234,13 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * Ensure newly-added widgets have empty instances so they
+        * will be recognized.
</ins><span class="cx">    *
</span><ins>+        * This is necessary because the customizer's setting preview
+        * filters are added after the widgets_init action, which is
+        * too late for the widgets to be set up properly.
</ins><span class="cx">    *
</span><del>-        * Ensure that newly-added widgets will have empty instances so that they will be recognized.
-        * This is necessary because the customizer's setting preview filters are added after the widgets_init action,
-        * which is too late for the widgets to be set up properly.
-        *
</del><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -239,7 +253,7 @@
</span><span class="cx">                  $parsed_setting_id = $this->parse_widget_setting_id( $setting_id );
</span><span class="cx">                  $widget_number     = $parsed_setting_id['number'];
</span><span class="cx"> 
</span><del>-                       // Single widget
</del><ins>+                        // Single widget.
</ins><span class="cx">                   if ( is_null( $widget_number ) ) {
</span><span class="cx">                          if ( false === $instance && empty( $value ) ) {
</span><span class="cx">                                  $instance = array();
</span><span class="lines">@@ -259,9 +273,12 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Remove filters added in setup_widget_addition_previews() which ensure that
-        * widgets are populating the options during widgets_init
</del><ins>+         * Remove pre-preview filters.
</ins><span class="cx">    *
</span><ins>+        * Removes filters added in setup_widget_addition_previews()
+        * to ensure widgets are populating the options during
+        * 'widgets_init'.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   */
</span><span class="lines">@@ -273,13 +290,18 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Make sure that all widgets get loaded into customizer; these actions are also done in the wp_ajax_save_widget()
</del><ins>+         * Make sure all widgets get loaded into the Customizer.
</ins><span class="cx">    *
</span><ins>+        * Note: these actions are also fired in wp_ajax_update_widget().
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   */
</span><span class="cx">  public function customize_controls_init() {
</span><ins>+               /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx">           do_action( 'load-widgets.php' );
</span><ins>+
+               /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx">           do_action( 'widgets.php' );
</span><span class="cx"> 
</span><span class="cx">          /** This action is documented in wp-admin/widgets.php */
</span><span class="lines">@@ -287,9 +309,12 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * When in preview, invoke customize_register for settings after WordPress is
-        * loaded so that all filters have been initialized (e.g. Widget Visibility)
</del><ins>+         * Ensure widgets are available for all types of previews.
</ins><span class="cx">    *
</span><ins>+        * When in preview, hook to 'customize_register' for settings
+        * after WordPress is loaded so that all filters have been
+        * initialized (e.g. Widget Visibility).
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   */
</span><span class="lines">@@ -302,7 +327,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Register customizer settings and controls for all sidebars and widgets
</del><ins>+         * Register customizer settings and controls for all sidebars and widgets.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -319,8 +344,9 @@
</span><span class="cx">          $new_setting_ids = array();
</span><span class="cx"> 
</span><span class="cx">          /*
</span><del>-                * Register a setting for all widgets, including those which are active, inactive, and orphaned
-                * since a widget may get suppressed from a sidebar via a plugin (like Widget Visibility).
</del><ins>+                 * Register a setting for all widgets, including those which are active,
+                * inactive, and orphaned since a widget may get suppressed from a sidebar
+                * via a plugin (like Widget Visibility).
</ins><span class="cx">            */
</span><span class="cx">          foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
</span><span class="cx">                  $setting_id   = $this->get_setting_id( $widget_id );
</span><span class="lines">@@ -339,9 +365,7 @@
</span><span class="cx">                  $is_inactive_widgets   = ( 'wp_inactive_widgets' === $sidebar_id );
</span><span class="cx">                  $is_active_sidebar     = ( $is_registered_sidebar && ! $is_inactive_widgets );
</span><span class="cx"> 
</span><del>-                       /**
-                        * Add setting for managing the sidebar's widgets
-                        */
</del><ins>+                        // Add setting for managing the sidebar's widgets.
</ins><span class="cx">                   if ( $is_registered_sidebar || $is_inactive_widgets ) {
</span><span class="cx">                          $setting_id   = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
</span><span class="cx">                          $setting_args = $this->get_setting_args( $setting_id );
</span><span class="lines">@@ -350,9 +374,7 @@
</span><span class="cx">                          $this->manager->add_setting( $setting_id, $setting_args );
</span><span class="cx">                          $new_setting_ids[] = $setting_id;
</span><span class="cx"> 
</span><del>-                               /**
-                                * Add section to contain controls
-                                */
</del><ins>+                                // Add section to contain controls.
</ins><span class="cx">                           $section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
</span><span class="cx">                          if ( $is_active_sidebar ) {
</span><span class="cx">                                  $section_args = array(
</span><span class="lines">@@ -422,7 +444,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Covert a widget_id into its corresponding customizer setting id (option name)
</del><ins>+         * Covert a widget_id into its corresponding customizer setting ID (option name).
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -440,13 +462,15 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Core widgets which may have controls wider than 250, but can still be
-        * shown in the narrow customizer panel. The RSS and Text widgets in Core,
-        * for example, have widths of 400 and yet they still render fine in the
-        * customizer panel. This method will return all Core widgets as being
-        * not wide, but this can be overridden with the is_wide_widget_in_customizer
-        * filter.
</del><ins>+         * Determine whether the widget is considered "wide".
</ins><span class="cx">    *
</span><ins>+        * Core widgets which may have controls wider than 250, but can
+        * still be shown in the narrow customizer panel. The RSS and Text
+        * widgets in Core, for example, have widths of 400 and yet they
+        * still render fine in the customizer panel. This method will
+        * return all Core widgets as being not wide, but this can be
+        * overridden with the is_wide_widget_in_customizer filter.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -468,8 +492,7 @@
</span><span class="cx">           * @param bool   $is_wide   Whether the widget is wide, Default false.
</span><span class="cx">           * @param string $widget_id Widget ID.
</span><span class="cx">           */
</span><del>-               $is_wide = apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
-               return $is_wide;
</del><ins>+                return apply_filters( 'is_wide_widget_in_customizer', $is_wide, $widget_id );
</ins><span class="cx">   }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><span class="lines">@@ -503,7 +526,7 @@
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="cx">   * @param string $setting_id Widget setting ID.
</span><del>-        * @return WP_Error|array Array contain a widget's id_base and number components,
</del><ins>+         * @return WP_Error|array Array containing a widget's id_base and number components,
</ins><span class="cx">    *                        or a WP_Error object.
</span><span class="cx">   */
</span><span class="cx">  public function parse_widget_setting_id( $setting_id ) {
</span><span class="lines">@@ -517,7 +540,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Enqueue scripts and styles for customizer panel and export data to JS.
</del><ins>+         * Enqueue scripts and styles for customizer panel and export data to JavaScript.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -526,8 +549,10 @@
</span><span class="cx">          wp_enqueue_style( 'customize-widgets' );
</span><span class="cx">          wp_enqueue_script( 'customize-widgets' );
</span><span class="cx"> 
</span><del>-               // Export available widgets with control_tpl removed from model
-               // since plugins need templates to be in the DOM
</del><ins>+                /*
+                * Export available widgets with control_tpl removed from model
+                * since plugins need templates to be in the DOM.
+                */
</ins><span class="cx">           $available_widgets = array();
</span><span class="cx">          foreach ( $this->get_available_widgets() as $available_widget ) {
</span><span class="cx">                  unset( $available_widget['control_tpl'] );
</span><span class="lines">@@ -562,7 +587,10 @@
</span><span class="cx">                  '
</span><span class="cx">          );
</span><span class="cx"> 
</span><del>-               // Why not wp_localize_script? Because we're not localizing, and it forces values into strings.
</del><ins>+                /*
+                * Why not wp_localize_script? Because we're not localizing,
+                * and it forces values into strings.
+                */
</ins><span class="cx">           global $wp_scripts;
</span><span class="cx">          $exports = array(
</span><span class="cx">                  'nonce' => wp_create_nonce( 'update-widget' ),
</span><span class="lines">@@ -594,7 +622,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Render the widget form control templates into the DOM so that plugin scripts can manipulate them
</del><ins>+         * Render the widget form control templates into the DOM.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -618,7 +646,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Get common arguments to supply when constructing a customizer setting
</del><ins>+         * Get common arguments to supply when constructing a Customizer setting.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -635,14 +663,25 @@
</span><span class="cx">                  'default' => array(),
</span><span class="cx">          );
</span><span class="cx">          $args = array_merge( $args, $overrides );
</span><del>-               $args = apply_filters( 'widget_customizer_setting_args', $args, $id );
-               return $args;
</del><ins>+
+               /**
+                * Filter the common arguments supplied when constructing a Customizer setting.
+                *
+                * @since 3.9.0
+                *
+                * @see WP_Customize_Setting
+                *
+                * @param array  $args Array of Customizer setting arguments.
+                * @param string $id   Widget setting ID.
+                */
+               return apply_filters( 'widget_customizer_setting_args', $args, $id );
</ins><span class="cx">   }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Make sure that a sidebars_widgets[x] only ever consists of actual widget IDs.
-        * Used as sanitize_callback for each sidebars_widgets setting.
</del><ins>+         * Make sure that sidebar widget arrays only ever contain widget IDS.
</ins><span class="cx">    *
</span><ins>+        * Used as the 'sanitize_callback' for each $sidebars_widgets setting.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -668,7 +707,8 @@
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="cx">   * @see wp_list_widgets()
</span><del>-        * @return array
</del><ins>+         *
+        * @return array List of available widgets.
</ins><span class="cx">    */
</span><span class="cx">  public function get_available_widgets() {
</span><span class="cx">          static $available_widgets = array();
</span><span class="lines">@@ -726,7 +766,7 @@
</span><span class="cx">                  $list_widget_controls_args = wp_list_widget_controls_dynamic_sidebar( array( 0 => $args, 1 => $widget['params'][0] ) );
</span><span class="cx">                  $control_tpl = $this->get_widget_control( $list_widget_controls_args );
</span><span class="cx"> 
</span><del>-                       // The properties here are mapped to the Backbone Widget model
</del><ins>+                        // The properties here are mapped to the Backbone Widget model.
</ins><span class="cx">                   $available_widget = array_merge(
</span><span class="cx">                          $available_widget,
</span><span class="cx">                          array(
</span><span class="lines">@@ -764,8 +804,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Invoke wp_widget_control() but capture the output buffer and transform the markup
-        * so that it can be used in the customizer.
</del><ins>+         * Get the widget control markup.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -786,7 +825,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Add hooks for the customizer preview
</del><ins>+         * Add hooks for the customizer preview.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -799,13 +838,14 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * When previewing, make sure the proper previewing widgets are used.
</ins><span class="cx">    *
</span><ins>+        * Because wp_get_sidebars_widgets() gets called early at init
+        * (via wp_convert_widget_settings()) and can set global variable
+        * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' )
+        * before the customizer preview filter is added, we have to reset
+        * it after the filter has been added.
</ins><span class="cx">    *
</span><del>-        * When previewing, make sure the proper previewing widgets are used. Because wp_get_sidebars_widgets()
-        * gets called early at init (via wp_convert_widget_settings()) and can set global variable
-        * $_wp_sidebars_widgets to the value of get_option( 'sidebars_widgets' ) before the customizer
-        * preview filter is added, we have to reset it after the filter has been added.
-        *
</del><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -813,12 +853,13 @@
</span><span class="cx">   */
</span><span class="cx">  public function preview_sidebars_widgets( $sidebars_widgets ) {
</span><span class="cx">          $sidebars_widgets = get_option( 'sidebars_widgets' );
</span><ins>+
</ins><span class="cx">           unset( $sidebars_widgets['array_version'] );
</span><span class="cx">          return $sidebars_widgets;
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Enqueue scripts for the customizer preview
</del><ins>+         * Enqueue scripts for the Customizer preview.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -851,7 +892,8 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page.
</del><ins>+         * At the very end of the page, at the very end of the wp_footer,
+        * communicate the sidebars that appeared on the page.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -879,7 +921,7 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Keep track of the widgets that were rendered
</del><ins>+         * Keep track of the widgets that were rendered.
</ins><span class="cx">    *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="lines">@@ -891,9 +933,13 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Keep track of the times that is_active_sidebar() is called in the template, and assume that this
-        * means that the sidebar would be rendered on the template if there were widgets populating it.
</del><ins>+         * Tally the sidebars rendered via is_active_sidebar().
</ins><span class="cx">    *
</span><ins>+        * Keep track of the times that is_active_sidebar() is called
+        * in the template, and assume that this means that the sidebar
+        * would be rendered on the template if there were widgets
+        * populating it.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -904,15 +950,21 @@
</span><span class="cx">          if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx">                  $this->rendered_sidebars[] = $sidebar_id;
</span><span class="cx">          }
</span><del>-               // We may need to force this to true, and also force-true the value for dynamic_sidebar_has_widgets
-               // if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
</del><ins>+                /*
+                * We may need to force this to true, and also force-true the value
+                * for 'dynamic_sidebar_has_widgets' if we want to ensure that there
+                * is an area to drop widgets into, if the sidebar is empty.
+                */
</ins><span class="cx">           return $is_active;
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Keep track of the times that dynamic_sidebar() is called in the template, and assume that this
-        * means that the sidebar would be rendered on the template if there were widgets populating it.
</del><ins>+         * Tally the sidebars rendered via dynamic_sidebar().
</ins><span class="cx">    *
</span><ins>+        * Keep track of the times that dynamic_sidebar() is called in the template,
+        * and assume this means the sidebar would be rendered on the template if
+        * there were widgets populating it.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -923,9 +975,11 @@
</span><span class="cx">          if ( isset( $GLOBALS['wp_registered_sidebars'][$sidebar_id] ) ) {
</span><span class="cx">                  $this->rendered_sidebars[] = $sidebar_id;
</span><span class="cx">          }
</span><ins>+
</ins><span class="cx">           /*
</span><del>-                * We may need to force this to true, and also force-true the value for is_active_sidebar
-                * if we want to ensure that there is an area to drop widgets into, if the sidebar is empty.
</del><ins>+                 * We may need to force this to true, and also force-true the value
+                * for 'is_active_sidebar' if we want to ensure there is an area to
+                * drop widgets into, if the sidebar is empty.
</ins><span class="cx">            */
</span><span class="cx">          return $has_widgets;
</span><span class="cx">  }
</span><span class="lines">@@ -958,8 +1012,6 @@
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><del>-        * @see Widget_Customizer::sanitize_widget_js_instance()
-        *
</del><span class="cx">    * @param array $value Widget instance to sanitize.
</span><span class="cx">   * @return array Sanitized widget instance.
</span><span class="cx">   */
</span><span class="lines">@@ -997,8 +1049,6 @@
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><del>-        * @see Widget_Customizer::sanitize_widget_instance()
-        *
</del><span class="cx">    * @param array $value Widget instance to convert to JSON.
</span><span class="cx">   * @return array JSON-converted widget instance.
</span><span class="cx">   */
</span><span class="lines">@@ -1016,9 +1066,11 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Strip out widget IDs for widgets which are no longer registered, such
-        * as the case when a plugin orphans a widget in a sidebar when it is deactivated.
</del><ins>+         * Strip out widget IDs for widgets which are no longer registered.
</ins><span class="cx">    *
</span><ins>+        * One example where this might happen is when a plugin orphans a widget
+        * in a sidebar upon deactivation.
+        *
</ins><span class="cx">    * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="lines">@@ -1040,7 +1092,8 @@
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><span class="cx">   * @param  string $widget_id Widget ID.
</span><del>-        * @return WP_Error|array Array containing the updated widget information. WP_Error, otherwise.
</del><ins>+         * @return WP_Error|array Array containing the updated widget information.
+        *                        A WP_Error object, otherwise.
</ins><span class="cx">    */
</span><span class="cx">  public function call_widget_update( $widget_id ) {
</span><span class="cx">          global $wp_registered_widget_updates, $wp_registered_widget_controls;
</span><span class="lines">@@ -1132,16 +1185,19 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Allow customizer to update a widget using its form, but return the new
</del><ins>+         * Update widget settings asynchronously.
+        *
+        * Allows the Customizer to update a widget using its form, but return the new
</ins><span class="cx">    * instance info via Ajax instead of saving it to the options table.
</span><ins>+        *
</ins><span class="cx">    * Most code here copied from wp_ajax_save_widget()
</span><span class="cx">   *
</span><span class="cx">   * @since 3.9.0
</span><span class="cx">   * @access public
</span><span class="cx">   *
</span><del>-        * @see wp_ajax_save_widget
</del><ins>+         * @see wp_ajax_save_widget()
+        *
</ins><span class="cx">    * @todo Reuse wp_ajax_save_widget now that we have option transactions?
</span><del>-        * @action wp_ajax_update_widget
</del><span class="cx">    */
</span><span class="cx">  public function wp_ajax_update_widget() {
</span><span class="cx"> 
</span><span class="lines">@@ -1159,7 +1215,10 @@
</span><span class="cx">                  wp_send_json_error();
</span><span class="cx">          }
</span><span class="cx"> 
</span><ins>+               /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx">           do_action( 'load-widgets.php' );
</span><ins>+
+               /** This action is documented in wp-admin/includes/ajax-actions.php */
</ins><span class="cx">           do_action( 'widgets.php' );
</span><span class="cx"> 
</span><span class="cx">          /** This action is documented in wp-admin/widgets.php */
</span><span class="lines">@@ -1189,41 +1248,65 @@
</span><span class="cx">   ***************************************************************************/
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * @var array $_captured_options values updated while capturing is happening
</del><ins>+         * List of captured widget option updates.
+        *
+        * @since 3.9.0
+        * @access protected
+        * @var array $_captured_options Values updated while option capture is happening.
</ins><span class="cx">    */
</span><span class="cx">  protected $_captured_options = array();
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * @var bool $_is_current whether capturing is currently happening or not
</del><ins>+         * Whether option capture is currently happening.
+        *
+        * @since 3.9.0
+        * @access protected
+        * @var bool $_is_current Whether option capture is currently happening or not.
</ins><span class="cx">    */
</span><span class="cx">  protected $_is_capturing_option_updates = false;
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * @param $option_name
-        * @return boolean
</del><ins>+         * Determine whether the captured option update should be ignored.
+        *
+        * @since 3.9.0
+        * @access protected
+        *
+        * @param string $option_name Option name.
+        * @return boolean Whether the option capture is ignored.
</ins><span class="cx">    */
</span><span class="cx">  protected function is_option_capture_ignored( $option_name ) {
</span><span class="cx">          return ( 0 === strpos( $option_name, '_transient_' ) );
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Get options updated
-        * @return array
</del><ins>+         * Retrieve captured widget option updates.
+        *
+        * @since 3.9.0
+        * @access protected
+        *
+        * @return array Array of captured options.
</ins><span class="cx">    */
</span><span class="cx">  protected function get_captured_options() {
</span><span class="cx">          return $this->_captured_options;
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Get the number of options updated
-        * @return bool
</del><ins>+         * Get the number of captured widget option updates.
+        *
+        * @since 3.9.0
+        * @access protected
+        *
+        * @return int Number of updated options.
</ins><span class="cx">    */
</span><span class="cx">  protected function count_captured_options() {
</span><span class="cx">          return count( $this->_captured_options );
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Start keeping track of changes to options, and cache their new values
</del><ins>+         * Start keeping track of changes to widget options, caching new values.
+        *
+        * @since 3.9.0
+        * @access protected
</ins><span class="cx">    */
</span><span class="cx">  protected function start_capturing_option_updates() {
</span><span class="cx">          if ( $this->_is_capturing_option_updates ) {
</span><span class="lines">@@ -1235,13 +1318,15 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * Pre-filter captured option values before updating.
+        *
</ins><span class="cx">    * @access private
</span><span class="cx">   * @param mixed $new_value
</span><span class="cx">   * @param string $option_name
</span><span class="cx">   * @param mixed $old_value
</span><span class="cx">   * @return mixed
</span><span class="cx">   */
</span><del>-       public function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
</del><ins>+        private function _capture_filter_pre_update_option( $new_value, $option_name, $old_value ) {
</ins><span class="cx">           if ( $this->is_option_capture_ignored( $option_name ) ) {
</span><span class="cx">                  return;
</span><span class="cx">          }
</span><span class="lines">@@ -1256,11 +1341,13 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><ins>+        * Pre-filter captured option values before retrieving.
+        *
</ins><span class="cx">    * @access private
</span><del>-        * @param mixed $value
</del><ins>+         * @param mixed $value Option
</ins><span class="cx">    * @return mixed
</span><span class="cx">   */
</span><del>-       public function _capture_filter_pre_get_option( $value ) {
</del><ins>+        private function _capture_filter_pre_get_option( $value ) {
</ins><span class="cx">           $option_name = preg_replace( '/^pre_option_/', '', current_filter() );
</span><span class="cx">          if ( isset( $this->_captured_options[$option_name] ) ) {
</span><span class="cx">                  $value = $this->_captured_options[$option_name];
</span><span class="lines">@@ -1271,7 +1358,10 @@
</span><span class="cx">  }
</span><span class="cx"> 
</span><span class="cx">  /**
</span><del>-        * Undo any changes to the options since start_capturing_option_updates() was called
</del><ins>+         * Undo any changes to the options since options capture began.
+        *
+        * @since 3.9.0
+        * @access protected
</ins><span class="cx">    */
</span><span class="cx">  protected function stop_capturing_option_updates() {
</span><span class="cx">          if ( ! $this->_is_capturing_option_updates ) {
</span></span></pre>
</div>
</div>

</body>
</html>