WordPress.org
Get WordPress

Make WordPress Core

Ticket #30315: 30315.1.diff

File 30315.1.diff, 6.3 KB (added by jazzs3quence, 11 years ago)

Cleaned up some comments and added @since versions to the docblocks added in the previous patch

  • wp-includes/widgets.php

     
    2525
    2626        public $id_base;                        // Root id for all widgets of this type.
    2727        public $name;                           // Name for this widget type.
    28         public $widget_options; // Option array passed to wp_register_sidebar_widget()
     28        public $widget_options;     // Option array passed to wp_register_sidebar_widget()
    2929        public $control_options;        // Option array passed to wp_register_widget_control()
    3030
    31         public $number = false; // Unique ID number of the current instance.
    32         public $id = false;             // Unique ID string of the current instance (id_base-number)
     31        public $number = false;     // Unique ID number of the current instance.
     32        public $id = false;                 // Unique ID string of the current instance (id_base-number)
    3333        public $updated = false;        // Set true when we update the data after a POST submit - makes sure we don't do it twice.
    3434
    3535        // Member functions that you must over-ride.
    3636
    37         /** Echo the widget content.
     37        /**
     38         * Echo the widget content.
    3839         *
    3940         * Subclasses should over-ride this function to generate their widget code.
    4041         *
     42         * @since 2.8.0
     43         *
    4144         * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
    4245         * @param array $instance The settings for the particular instance of the widget
    4346         */
    … …  
    4548                die('function WP_Widget::widget() must be over-ridden in a sub-class.');
    4649        }
    4750
    48         /** Update a particular instance.
     51        /**
     52         * Update a particular instance.
    4953         *
    5054         * This function should check that $new_instance is set correctly.
    5155         * The newly calculated value of $instance should be returned.
    5256         * If "false" is returned, the instance won't be saved/updated.
    5357         *
     58         * @since 2.8.0
     59         *
    5460         * @param array $new_instance New settings for this instance as input by the user via form()
    5561         * @param array $old_instance Old settings for this instance
    5662         * @return array Settings to save or bool false to cancel saving
    … …  
    5965                return $new_instance;
    6066        }
    6167
    62         /** Echo the settings update form
     68        /**
     69         * Echo the settings update form
    6370         *
     71         * @since 2.8.0
     72         *
    6473         * @param array $instance Current settings
    6574         */
    6675        public function form($instance) {
    … …  
    122131                return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
    123132        }
    124133
    125         // Private Functions. Don't worry about these.
    126 
     134        /**
     135         * Register all widget instances of this widget class.
     136         *
     137         * @since 2.8.0
     138         *
     139         * @access private
     140         */
    127141        public function _register() {
    128142                $settings = $this->get_settings();
    129143                $empty = true;
    … …  
    146160                }
    147161        }
    148162
     163        /**
     164         * Set the internal order number for the widget instance.
     165         *
     166         * @since 2.8.0
     167         *
     168         * @access private
     169         *
     170         * @param int $number The unique order number of this widget instance
     171         *                    compared to other instances of the same class.
     172         */
    149173        public function _set($number) {
    150174                $this->number = $number;
    151175                $this->id = $this->id_base . '-' . $number;
    … …  
    362386                return $return;
    363387        }
    364388
    365         /** Helper function: Registers a single instance. */
     389        /**
     390         * Register an instance of the widget class.
     391         *
     392         * @since 2.8.0
     393         *
     394         * @access private
     395         *
     396         * @param  integer $number The unique order number of this widget instance
     397         *                         compared to other instances of the same class.
     398         */
    366399        public function _register_one($number = -1) {
    367400                wp_register_sidebar_widget(     $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
    368401                _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
    369402                _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
    370403        }
    371404
     405        /**
     406         * Save the settings for all instances of the widget class.
     407         *
     408         * @since 2.8.0
     409         *
     410         * @param array $settings Multi-dimensional array of widget instance settings.
     411         */
    372412        public function save_settings($settings) {
    373413                $settings['_multiwidget'] = 1;
    374414                update_option( $this->option_name, $settings );
    375415        }
    376416
     417        /**
     418         * Get the settings for all instances of the widget class.
     419         *
     420         * @since 2.8.0
     421         *
     422         * @return array Multi-dimensional array of widget instance settings.
     423         */
    377424        public function get_settings() {
     425
    378426                $settings = get_option($this->option_name);
    379427
    380428                if ( false === $settings && isset($this->alt_option_name) )
    … …  
    407455                add_action( 'widgets_init', array( $this, '_register_widgets' ), 100 );
    408456        }
    409457
     458        /**
     459         * Register a widget class.
     460         *
     461         * @since 2.8.0
     462         *
     463         * @param  mixed $widget_class A subclass of WP_Widget.
     464         */
    410465        public function register($widget_class) {
    411466                $this->widgets[$widget_class] = new $widget_class();
    412467        }
    413468
     469        /**
     470         * Unregister a widget class.
     471         *
     472         * @since 2.8.0
     473         *
     474         * @param  mixed $widget_class A subclass of WP_Widget.
     475         */
    414476        public function unregister($widget_class) {
    415477                if ( isset($this->widgets[$widget_class]) )
    416478                        unset($this->widgets[$widget_class]);
    … …  
    448510$wp_registered_sidebars = array();
    449511
    450512/**
    451  * Stores the registered widgets.
     513 * Stores instances of widgets.
    452514 *
    453515 * @global array $wp_registered_widgets
    454516 * @since 2.2.0
    … …  
    683745}
    684746
    685747/**
    686  * Register widget for use in sidebars.
     748 * Register an instance of a widget.
    687749 *
    688750 * The default widget option is 'classname' that can be overridden.
    689751 *
    … …  
    698760 * @param int|string $id Widget ID.
    699761 * @param string $name Widget display title.
    700762 * @param callback $output_callback Run when widget is called.
    701  * @param array|string $options Optional. Widget Options.
     763 * @param array $options {
     764 *     An array of supplementary widget options for the instance. Optional.
     765 *
     766 *     @type string $classname Classname for the widget's HTML container.
     767 *                             Optional. Defaults to the output callback.
     768 * }
    702769 * @param mixed $params,... Widget parameters to add to widget.
    703770 * @return null Will return if $output_callback is empty after removing widget.
    704771 */
    … …  
    12021269/* Internal Functions */
    12031270
    12041271/**
    1205  * Retrieve full list of sidebars and their widgets.
     1272 * Retrieve full list of sidebars and their widget instance IDs.
    12061273 *
    12071274 * Will upgrade sidebar widget list, if needed. Will also save updated list, if
    12081275 * needed.