From 43399f4ff7f72332dacb5bbbb0b3ef4049b21e8d Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Fri, 4 Mar 2016 02:01:15 +0000 Subject: [PATCH] Docs: Improve syntax and correct documentation throughout a variety of methods in `WP_Customize_Widgets`. See #32246. See #35986. git-svn-id: https://develop.svn.wordpress.org/trunk@36842 602fd350-edb4-49c9-b593-d223f7449a82 --- .../class-wp-customize-widgets.php | 218 +++++++++--------- 1 file changed, 107 insertions(+), 111 deletions(-) diff --git a/src/wp-includes/class-wp-customize-widgets.php b/src/wp-includes/class-wp-customize-widgets.php index 67892beb3b..a417c46904 100644 --- a/src/wp-includes/class-wp-customize-widgets.php +++ b/src/wp-includes/class-wp-customize-widgets.php @@ -112,7 +112,7 @@ final class WP_Customize_Widgets { } /** - * Get the widget setting type given a setting ID. + * Retrieves the widget setting type given a setting ID. * * @since 4.2.0 * @access protected @@ -136,7 +136,8 @@ final class WP_Customize_Widgets { } /** - * Inspect the incoming customized data for any widget settings, and dynamically add them up-front so widgets will be initialized properly. + * Inspects the incoming customized data for any widget settings, and dynamically adds + * them up-front so widgets will be initialized properly. * * @since 4.2.0 * @access public @@ -168,7 +169,7 @@ final class WP_Customize_Widgets { } /** - * Determine the arguments for a dynamically-created setting. + * Determines the arguments for a dynamically-created setting. * * @since 4.2.0 * @access public @@ -185,10 +186,9 @@ final class WP_Customize_Widgets { } /** - * Get an unslashed post value or return a default. + * Retrieves an unslashed post value or return a default. * * @since 3.9.0 - * * @access protected * * @param string $name Post value. @@ -237,18 +237,18 @@ final class WP_Customize_Widgets { } /** - * Filter old_sidebars_widgets_data Customizer setting. + * Filters old_sidebars_widgets_data Customizer setting. * - * When switching themes, filter the Customizer setting - * old_sidebars_widgets_data to supply initial $sidebars_widgets before they - * were overridden by retrieve_widgets(). The value for - * old_sidebars_widgets_data gets set in the old theme's sidebars_widgets + * When switching themes, filter the Customizer setting old_sidebars_widgets_data + * to supply initial $sidebars_widgets before they were overridden by retrieve_widgets(). + * The value for old_sidebars_widgets_data gets set in the old theme's sidebars_widgets * theme_mod. * - * @see WP_Customize_Widgets::handle_theme_switch() * @since 3.9.0 * @access public * + * @see WP_Customize_Widgets::handle_theme_switch() + * * @param array $old_sidebars_widgets * @return array */ @@ -257,16 +257,16 @@ final class WP_Customize_Widgets { } /** - * Filter sidebars_widgets option for theme switch. + * Filters sidebars_widgets option for theme switch. * - * When switching themes, the retrieve_widgets() function is run when the - * Customizer initializes, and then the new sidebars_widgets here get - * supplied as the default value for the sidebars_widgets option. + * When switching themes, the retrieve_widgets() function is run when the Customizer initializes, + * and then the new sidebars_widgets here get supplied as the default value for the sidebars_widgets + * option. * - * @see WP_Customize_Widgets::handle_theme_switch() * @since 3.9.0 * @access public * + * @see WP_Customize_Widgets::handle_theme_switch() * @global array $sidebars_widgets * * @param array $sidebars_widgets @@ -279,7 +279,7 @@ final class WP_Customize_Widgets { } /** - * Make sure all widgets get loaded into the Customizer. + * Ensures all widgets get loaded into the Customizer. * * Note: these actions are also fired in wp_ajax_update_widget(). * @@ -298,11 +298,10 @@ final class WP_Customize_Widgets { } /** - * Ensure widgets are available for all types of previews. + * Ensures widgets are available for all types of previews. * - * When in preview, hook to 'customize_register' for settings - * after WordPress is loaded so that all filters have been - * initialized (e.g. Widget Visibility). + * When in preview, hook to 'customize_register' for settings after WordPress is loaded + * so that all filters have been initialized (e.g. Widget Visibility). * * @since 3.9.0 * @access public @@ -316,7 +315,7 @@ final class WP_Customize_Widgets { } /** - * Register Customizer settings and controls for all sidebars and widgets. + * Registers Customizer settings and controls for all sidebars and widgets. * * @since 3.9.0 * @access public @@ -466,7 +465,7 @@ final class WP_Customize_Widgets { } /** - * Return whether the widgets panel is active, based on whether there are sidebars registered. + * Determines whether the widgets panel is active, based on whether there are sidebars registered. * * @since 4.4.0 * @access public @@ -482,7 +481,7 @@ final class WP_Customize_Widgets { } /** - * Covert a widget_id into its corresponding Customizer setting ID (option name). + * Converts a widget_id into its corresponding Customizer setting ID (option name). * * @since 3.9.0 * @access public @@ -501,13 +500,13 @@ final class WP_Customize_Widgets { } /** - * Determine whether the widget is considered "wide". + * Determines whether the widget is considered "wide". * - * 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 + * 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. * * @since 3.9.0 @@ -538,7 +537,7 @@ final class WP_Customize_Widgets { } /** - * Covert a widget ID into its id_base and number components. + * Converts a widget ID into its id_base and number components. * * @since 3.9.0 * @access public @@ -563,7 +562,7 @@ final class WP_Customize_Widgets { } /** - * Convert a widget setting ID (option path) to its id_base and number components. + * Converts a widget setting ID (option path) to its id_base and number components. * * @since 3.9.0 * @access public @@ -584,7 +583,7 @@ final class WP_Customize_Widgets { } /** - * Call admin_print_styles-widgets.php and admin_print_styles hooks to + * Calls admin_print_styles-widgets.php and admin_print_styles hooks to * allow custom styles from plugins. * * @since 3.9.0 @@ -599,7 +598,7 @@ final class WP_Customize_Widgets { } /** - * Call admin_print_scripts-widgets.php and admin_print_scripts hooks to + * Calls admin_print_scripts-widgets.php and admin_print_scripts hooks to * allow custom scripts from plugins. * * @since 3.9.0 @@ -614,7 +613,7 @@ final class WP_Customize_Widgets { } /** - * Enqueue scripts and styles for Customizer panel and export data to JavaScript. + * Enqueues scripts and styles for Customizer panel and export data to JavaScript. * * @since 3.9.0 * @access public @@ -706,7 +705,7 @@ final class WP_Customize_Widgets { } /** - * Render the widget form control templates into the DOM. + * Renders the widget form control templates into the DOM. * * @since 3.9.0 * @access public @@ -744,7 +743,7 @@ final class WP_Customize_Widgets { } /** - * Call admin_print_footer_scripts and admin_print_scripts hooks to + * Calls admin_print_footer_scripts and admin_print_scripts hooks to * allow custom scripts from plugins. * * @since 3.9.0 @@ -759,7 +758,7 @@ final class WP_Customize_Widgets { } /** - * Get common arguments to supply when constructing a Customizer setting. + * Retrieves common arguments to supply when constructing a Customizer setting. * * @since 3.9.0 * @access public @@ -800,7 +799,7 @@ final class WP_Customize_Widgets { } /** - * Make sure that sidebar widget arrays only ever contain widget IDS. + * Ensures sidebar widget arrays only ever contain widget IDS. * * Used as the 'sanitize_callback' for each $sidebars_widgets setting. * @@ -820,7 +819,7 @@ final class WP_Customize_Widgets { } /** - * Build up an index of all available widgets for use in Backbone models. + * Builds up an index of all available widgets for use in Backbone models. * * @since 3.9.0 * @access public @@ -907,7 +906,7 @@ final class WP_Customize_Widgets { } /** - * Naturally order available widgets by name. + * Naturally orders available widgets by name. * * @since 3.9.0 * @access protected @@ -921,7 +920,7 @@ final class WP_Customize_Widgets { } /** - * Get the widget control markup. + * Retrieves the widget control markup. * * @since 3.9.0 * @access public @@ -941,15 +940,15 @@ final class WP_Customize_Widgets { } /** - * Get the widget control markup parts. + * Retrieves the widget control markup parts. * * @since 4.4.0 * @access public * * @param array $args Widget control arguments. * @return array { - * @type string $control Markup for widget control wrapping form. - * @type string $content The contents of the widget form itself. + * @type string $control Markup for widget control wrapping form. + * @type string $content The contents of the widget form itself. * } */ public function get_widget_control_parts( $args ) { @@ -972,7 +971,7 @@ final class WP_Customize_Widgets { } /** - * Add hooks for the Customizer preview. + * Adds hooks for the Customizer preview. * * @since 3.9.0 * @access public @@ -984,7 +983,7 @@ final class WP_Customize_Widgets { } /** - * Refresh nonce for widget updates. + * Refreshes the nonce for widget updates. * * @since 4.2.0 * @access public @@ -998,13 +997,12 @@ final class WP_Customize_Widgets { } /** - * When previewing, make sure the proper previewing widgets are used. + * When previewing, ensures 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. + * Because wp_get_sidebars_widgets() gets called early at {@see '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, it has to be reset after the filter has been added. * * @since 3.9.0 * @access public @@ -1020,7 +1018,7 @@ final class WP_Customize_Widgets { } /** - * Enqueue scripts for the Customizer preview. + * Enqueues scripts for the Customizer preview. * * @since 3.9.0 * @access public @@ -1030,13 +1028,11 @@ final class WP_Customize_Widgets { } /** - * Insert default style for highlighted widget at early point so theme + * Inserts default style for highlighted widget at early point so theme * stylesheet can override. * * @since 3.9.0 * @access public - * - * @action wp_print_styles */ public function print_preview_css() { ?> @@ -1053,8 +1049,8 @@ final class WP_Customize_Widgets { } /** - * At the very end of the page, at the very end of the wp_footer, - * communicate the sidebars that appeared on the page. + * Communicates the sidebars that appeared on the page at the very end of the page, + * and at the very end of the wp_footer, * * @since 3.9.0 * @access public @@ -1087,7 +1083,7 @@ final class WP_Customize_Widgets { } /** - * Keep track of the widgets that were rendered. + * Tracks the widgets that were rendered. * * @since 3.9.0 * @access public @@ -1112,7 +1108,7 @@ final class WP_Customize_Widgets { } /** - * Determine if a sidebar is rendered on the page. + * Determines if a sidebar is rendered on the page. * * @since 4.0.0 * @access public @@ -1125,19 +1121,18 @@ final class WP_Customize_Widgets { } /** - * Tally the sidebars rendered via is_active_sidebar(). + * Tallies the sidebars rendered via is_active_sidebar(). * - * 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. + * 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. * * @since 3.9.0 * @access public * * @param bool $is_active Whether the sidebar is active. * @param string $sidebar_id Sidebar ID. - * @return bool + * @return bool Whether the sidebar is active. */ public function tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id ) { if ( is_registered_sidebar( $sidebar_id ) ) { @@ -1152,7 +1147,7 @@ final class WP_Customize_Widgets { } /** - * Tally the sidebars rendered via dynamic_sidebar(). + * Tallies the sidebars rendered via dynamic_sidebar(). * * 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 @@ -1163,7 +1158,7 @@ final class WP_Customize_Widgets { * * @param bool $has_widgets Whether the current sidebar has widgets. * @param string $sidebar_id Sidebar ID. - * @return bool + * @return bool Whether the current sidebar has widgets. */ public function tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id ) { if ( is_registered_sidebar( $sidebar_id ) ) { @@ -1179,7 +1174,7 @@ final class WP_Customize_Widgets { } /** - * Get MAC for a serialized widget instance string. + * Retrieves MAC for a serialized widget instance string. * * Allows values posted back from JS to be rejected if any tampering of the * data has occurred. @@ -1195,10 +1190,10 @@ final class WP_Customize_Widgets { } /** - * Sanitize a widget instance. + * Sanitizes a widget instance. * - * Unserialize the JS-instance for storing in the options. It's important - * that this filter only get applied to an instance once. + * Unserialize the JS-instance for storing in the options. It's important that this filter + * only get applied to an instance *once*. * * @since 3.9.0 * @access public @@ -1236,7 +1231,7 @@ final class WP_Customize_Widgets { } /** - * Convert widget instance into JSON-representable format. + * Converts a widget instance into JSON-representable format. * * @since 3.9.0 * @access public @@ -1259,7 +1254,7 @@ final class WP_Customize_Widgets { } /** - * Strip out widget IDs for widgets which are no longer registered. + * Strips out widget IDs for widgets which are no longer registered. * * One example where this might happen is when a plugin orphans a widget * in a sidebar upon deactivation. @@ -1279,9 +1274,9 @@ final class WP_Customize_Widgets { } /** - * Find and invoke the widget update and control callbacks. + * Finds and invokes the widget update and control callbacks. * - * Requires that $_POST be populated with the instance data. + * Requires that `$_POST` be populated with the instance data. * * @since 3.9.0 * @access public @@ -1406,18 +1401,17 @@ final class WP_Customize_Widgets { } /** - * Update widget settings asynchronously. + * Updates widget settings asynchronously. * * Allows the Customizer to update a widget using its form, but return the new * instance info via Ajax instead of saving it to the options table. * - * Most code here copied from wp_ajax_save_widget() + * Most code here copied from wp_ajax_save_widget(). * * @since 3.9.0 * @access public * * @see wp_ajax_save_widget() - * */ public function wp_ajax_update_widget() { @@ -1506,7 +1500,7 @@ final class WP_Customize_Widgets { } /** - * Add hooks for selective refresh. + * Adds hooks for selective refresh. * * @since 4.5.0 * @access public @@ -1524,7 +1518,7 @@ final class WP_Customize_Widgets { } /** - * Enqueue scripts for the Customizer preview. + * Enqueues scripts for the Customizer preview. * * @since 4.5.0 * @access public @@ -1599,25 +1593,25 @@ final class WP_Customize_Widgets { /** * List of the tag names seen for before_widget strings. * - * This is used in the filter_wp_kses_allowed_html filter to ensure that the + * This is used in the {@see 'filter_wp_kses_allowed_html'} filter to ensure that the * data-* attributes can be whitelisted. * * @since 4.5.0 - * @access private + * @access protected * @var array */ protected $before_widget_tags_seen = array(); /** - * Ensure that the HTML data-* attributes for selective refresh are allowed by kses. + * Ensures the HTML data-* attributes for selective refresh are allowed by kses. * - * This is needed in case the $before_widget is run through wp_kses() when printed. + * This is needed in case the `$before_widget` is run through wp_kses() when printed. * * @since 4.5.0 * @access public * * @param array $allowed_html Allowed HTML. - * @return array Allowed HTML. + * @return array (Maybe) modified allowed HTML. */ public function filter_wp_kses_allowed_data_attributes( $allowed_html ) { foreach ( array_keys( $this->before_widget_tags_seen ) as $tag_name ) { @@ -1644,7 +1638,7 @@ final class WP_Customize_Widgets { * This helps facilitate the uncommon scenario where a single sidebar is rendered multiple times on a template. * * @since 4.5.0 - * @access private + * @access protected * @var array */ protected $sidebar_instance_count = array(); @@ -1653,7 +1647,7 @@ final class WP_Customize_Widgets { * The current request's sidebar_instance_number context. * * @since 4.5.0 - * @access private + * @access protected * @var int */ protected $context_sidebar_instance_number; @@ -1662,17 +1656,18 @@ final class WP_Customize_Widgets { * Current sidebar ID being rendered. * * @since 4.5.0 - * @access private + * @access protected * @var array */ protected $current_dynamic_sidebar_id_stack = array(); /** - * Start keeping track of the current sidebar being rendered. + * Begins keeping track of the current sidebar being rendered. * * Insert marker before widgets are rendered in a dynamic sidebar. * * @since 4.5.0 + * @access public * * @param int|string $index Index, name, or ID of the dynamic sidebar. */ @@ -1688,11 +1683,12 @@ final class WP_Customize_Widgets { } /** - * Finish keeping track of the current sidebar being rendered. + * Finishes keeping track of the current sidebar being rendered. * - * Insert marker after widgets are rendered in a dynamic sidebar. + * Inserts a marker after widgets are rendered in a dynamic sidebar. * * @since 4.5.0 + * @access public * * @param int|string $index Index, name, or ID of the dynamic sidebar. */ @@ -1707,7 +1703,7 @@ final class WP_Customize_Widgets { * Current sidebar being rendered. * * @since 4.5.0 - * @access private + * @access protected * @var string */ protected $rendering_widget_id; @@ -1716,19 +1712,19 @@ final class WP_Customize_Widgets { * Current widget being rendered. * * @since 4.5.0 - * @access private + * @access protected * @var string */ protected $rendering_sidebar_id; /** - * Filter sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar. + * Filters sidebars_widgets to ensure the currently-rendered widget is the only widget in the current sidebar. * * @since 4.5.0 - * @access private + * @access protected * * @param array $sidebars_widgets Sidebars widgets. - * @return array Sidebars widgets. + * @return array Filtered sidebars widgets. */ public function filter_sidebars_widgets_for_rendering_widget( $sidebars_widgets ) { $sidebars_widgets[ $this->rendering_sidebar_id ] = array( $this->rendering_widget_id ); @@ -1736,19 +1732,19 @@ final class WP_Customize_Widgets { } /** - * Render a specific widget using the supplied sidebar arguments. + * Renders a specific widget using the supplied sidebar arguments. * * @since 4.5.0 * @access public * * @see dynamic_sidebar() * - * @param WP_Customize_Partial $partial Partial. + * @param WP_Customize_Partial $partial Partial. * @param array $context { * Sidebar args supplied as container context. * - * @type string $sidebar_id ID for sidebar for widget to render into. - * @type int [$sidebar_instance_number] Disambiguating instance number. + * @type string $sidebar_id ID for sidebar for widget to render into. + * @type int $sidebar_instance_number Disambiguating instance number. * } * @return string|false */ @@ -1813,7 +1809,7 @@ final class WP_Customize_Widgets { protected $_is_capturing_option_updates = false; /** - * Determine whether the captured option update should be ignored. + * Determines whether the captured option update should be ignored. * * @since 3.9.0 * @access protected @@ -1826,7 +1822,7 @@ final class WP_Customize_Widgets { } /** - * Retrieve captured widget option updates. + * Retrieves captured widget option updates. * * @since 3.9.0 * @access protected @@ -1838,13 +1834,13 @@ final class WP_Customize_Widgets { } /** - * Get the option that was captured from being saved. + * Retrieves the option that was captured from being saved. * * @since 4.2.0 * @access protected * * @param string $option_name Option name. - * @param mixed $default Optional. Default value to return if the option does not exist. + * @param mixed $default Optional. Default value to return if the option does not exist. Default false. * @return mixed Value set for the option. */ protected function get_captured_option( $option_name, $default = false ) { @@ -1857,7 +1853,7 @@ final class WP_Customize_Widgets { } /** - * Get the number of captured widget option updates. + * Retrieves the number of captured widget option updates. * * @since 3.9.0 * @access protected @@ -1869,7 +1865,7 @@ final class WP_Customize_Widgets { } /** - * Start keeping track of changes to widget options, caching new values. + * Begins keeping track of changes to widget options, caching new values. * * @since 3.9.0 * @access protected @@ -1885,7 +1881,7 @@ final class WP_Customize_Widgets { } /** - * Pre-filter captured option values before updating. + * Pre-filters captured option values before updating. * * @since 3.9.0 * @access public @@ -1910,7 +1906,7 @@ final class WP_Customize_Widgets { } /** - * Pre-filter captured option values before retrieving. + * Pre-filters captured option values before retrieving. * * @since 3.9.0 * @access public @@ -1932,7 +1928,7 @@ final class WP_Customize_Widgets { } /** - * Undo any changes to the options since options capture began. + * Undoes any changes to the options since options capture began. * * @since 3.9.0 * @access protected