From e34a587ea6594a07ba38ecb2f58c526c5b6a5144 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Tue, 18 Nov 2014 22:58:22 +0000 Subject: [PATCH] Add some missing inline documentation for methods in the `WP_Widget` class in wp-includes/widgets.php. Props ericlewis, jazzs3quence. See #30315. Built from https://develop.svn.wordpress.org/trunk@30382 git-svn-id: http://core.svn.wordpress.org/trunk@30379 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/widgets.php | 144 +++++++++++++++++++++++++++++----------- 1 file changed, 107 insertions(+), 37 deletions(-) diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index f3ca44a0d8..d113659d29 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -34,34 +34,49 @@ class WP_Widget { // Member functions that you must over-ride. - /** Echo the widget content. + /** + * Echo the widget content. * * Subclasses should over-ride this function to generate their widget code. * - * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget. - * @param array $instance The settings for the particular instance of the widget + * @since 2.8.0 + * @access public + * + * @param array $args Display arguments including before_title, after_title, + * before_widget, and after_widget. + * @param array $instance The settings for the particular instance of the widget. */ - public function widget($args, $instance) { + public function widget( $args, $instance ) { die('function WP_Widget::widget() must be over-ridden in a sub-class.'); } - /** Update a particular instance. + /** + * Update a particular instance. * - * This function should check that $new_instance is set correctly. - * The newly calculated value of $instance should be returned. - * If "false" is returned, the instance won't be saved/updated. + * This function should check that $new_instance is set correctly. The newly-calculated + * value of `$instance` should be returned. If false is returned, the instance won't be + * saved/updated. * - * @param array $new_instance New settings for this instance as input by the user via form() - * @param array $old_instance Old settings for this instance - * @return array Settings to save or bool false to cancel saving + * @since 2.8.0 + * @access public + * + * @param array $new_instance New settings for this instance as input by the user via + * {@see WP_Widget::form()}. + * @param array $old_instance Old settings for this instance. + * @return array Settings to save or bool false to cancel saving. */ - public function update($new_instance, $old_instance) { + public function update( $new_instance, $old_instance ) { return $new_instance; } - /** Echo the settings update form + /** + * Output the settings update form. * - * @param array $instance Current settings + * @since 2.8.0 + * @access public + * + * @param array $instance Current settings. + * @return string Default return is 'noform'. */ public function form($instance) { echo '

' . __('There are no options for this widget.') . '

'; @@ -71,17 +86,18 @@ class WP_Widget { // Functions you'll need to call. /** - * PHP5 constructor + * PHP5 constructor. * - * @param string $id_base Optional Base ID for the widget, lower case, - * if left empty a portion of the widget's class name will be used. Has to be unique. - * @param string $name Name for the widget displayed on the configuration page. - * @param array $widget_options Optional Passed to wp_register_sidebar_widget() - * - description: shown on the configuration page - * - classname - * @param array $control_options Optional Passed to wp_register_widget_control() - * - width: required if more than 250px - * - height: currently not used but may be needed in the future + * @since 2.8.0 + * @access public + * + * @param string $id_base Optional Base ID for the widget, lowercase and unique. If left empty, + * a portion of the widget's class name will be used Has to be unique. + * @param string $name Name for the widget displayed on the configuration page. + * @param array $widget_options Optional. Widget options. See {@see wp_register_sidebar_widget()} for + * information on accepted arguments. Default empty array. + * @param array $control_options Optional. Widget control options. See {@see wp_register_widget_control()} + * for information on accepted arguments. Default empty array. */ public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) { $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base); @@ -122,8 +138,12 @@ class WP_Widget { return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name; } - // Private Functions. Don't worry about these. - + /** + * Register all widget instances of this widget class. + * + * @since 2.8.0 + * @access private + */ public function _register() { $settings = $this->get_settings(); $empty = true; @@ -146,6 +166,15 @@ class WP_Widget { } } + /** + * Set the internal order number for the widget instance. + * + * @since 2.8.0 + * @access private + * + * @param int $number The unique order number of this widget instance compared to other + * instances of the same class. + */ public function _set($number) { $this->number = $number; $this->id = $this->id_base . '-' . $number; @@ -164,23 +193,39 @@ class WP_Widget { } /** - * Determine if we're in the Customizer; if true, then the object cache gets - * suspended and widgets should check this to decide whether they should - * store anything persistently to the object cache, to transients, or - * anywhere else. + * Determine whether the current request is inside the Customizer preview. + * + * If true -- the current request is inside the Customizer preview, then + * the object cache gets suspended and widgets should check this to decide + * whether they should store anything persistently to the object cache, + * to transients, or anywhere else. * * @since 3.9.0 + * @access public * - * @return bool True if Customizer is on, false if not. + * @return bool True if within the Customizer preview, false if not. */ public function is_preview() { global $wp_customize; return ( isset( $wp_customize ) && $wp_customize->is_preview() ) ; } - /** Generate the actual widget content. - * Just finds the instance and calls widget(). - * Do NOT over-ride this function. */ + /** + * Generate the actual widget content (Do NOT override). + * + * Finds the instance and calls {@see WP_Widget::widget()}. + * + * @access public + * + * @param array $args Display arguments. See {@see WP_Widget::widget()} for information + * on accepted arguments. + * @param int|array $widget_args { + * Optional. Internal order number of the widget instance, or array of multi-widget arguments. + * Default 1. + * + * @type int $number Number increment used for multiples of the same widget. + * } + */ public function display_callback( $args, $widget_args = 1 ) { if ( is_numeric($widget_args) ) $widget_args = array( 'number' => $widget_args ); @@ -362,19 +407,44 @@ class WP_Widget { return $return; } - /** Helper function: Registers a single instance. */ - public function _register_one($number = -1) { + /** + * Register an instance of the widget class. + * + * @since 2.8.0 + * @access private + * + * @param integer $number Optional. The unique order number of this widget instance + * compared to other instances of the same class. Default -1. + */ + public function _register_one( $number = -1 ) { wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) ); _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) ); _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) ); } - public function save_settings($settings) { + /** + * Save the settings for all instances of the widget class. + * + * @since 2.8.0 + * @access public + * + * @param array $settings Multi-dimensional array of widget instance settings. + */ + public function save_settings( $settings ) { $settings['_multiwidget'] = 1; update_option( $this->option_name, $settings ); } + /** + * Get the settings for all instances of the widget class. + * + * @since 2.8.0 + * @access public + * + * @return array Multi-dimensional array of widget instance settings. + */ public function get_settings() { + $settings = get_option($this->option_name); if ( false === $settings && isset($this->alt_option_name) )