WordPress.org

Make WordPress Core

Changeset 30382


Ignore:
Timestamp:
11/18/2014 10:57:34 PM (5 years ago)
Author:
DrewAPicture
Message:

Add some missing inline documentation for methods in the WP_Widget class in wp-includes/widgets.php.

Props ericlewis, jazzs3quence.
See #30315.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/widgets.php

    r30105 r30382  
    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     *
    41      * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
    42      * @param array $instance The settings for the particular instance of the widget
    43      */
    44     public function widget($args, $instance) {
     42     * @since 2.8.0
     43     * @access public
     44     *
     45     * @param array $args     Display arguments including before_title, after_title,
     46     *                        before_widget, and after_widget.
     47     * @param array $instance The settings for the particular instance of the widget.
     48     */
     49    public function widget( $args, $instance ) {
    4550        die('function WP_Widget::widget() must be over-ridden in a sub-class.');
    4651    }
    4752
    48     /** Update a particular instance.
    49      *
    50      * This function should check that $new_instance is set correctly.
    51      * The newly calculated value of $instance should be returned.
    52      * If "false" is returned, the instance won't be saved/updated.
    53      *
    54      * @param array $new_instance New settings for this instance as input by the user via form()
    55      * @param array $old_instance Old settings for this instance
    56      * @return array Settings to save or bool false to cancel saving
    57      */
    58     public function update($new_instance, $old_instance) {
     53    /**
     54     * Update a particular instance.
     55     *
     56     * This function should check that $new_instance is set correctly. The newly-calculated
     57     * value of `$instance` should be returned. If false is returned, the instance won't be
     58     * saved/updated.
     59     *
     60     * @since 2.8.0
     61     * @access public
     62     *
     63     * @param array $new_instance New settings for this instance as input by the user via
     64     *                            {@see WP_Widget::form()}.
     65     * @param array $old_instance Old settings for this instance.
     66     * @return array Settings to save or bool false to cancel saving.
     67     */
     68    public function update( $new_instance, $old_instance ) {
    5969        return $new_instance;
    6070    }
    6171
    62     /** Echo the settings update form
    63      *
    64      * @param array $instance Current settings
     72    /**
     73     * Output the settings update form.
     74     *
     75     * @since 2.8.0
     76     * @access public
     77     *
     78     * @param array $instance Current settings.
     79     * @return string Default return is 'noform'.
    6580     */
    6681    public function form($instance) {
     
    7287
    7388    /**
    74      * PHP5 constructor
    75      *
    76      * @param string $id_base Optional Base ID for the widget, lower case,
    77      * if left empty a portion of the widget's class name will be used. Has to be unique.
    78      * @param string $name Name for the widget displayed on the configuration page.
    79      * @param array $widget_options Optional Passed to wp_register_sidebar_widget()
    80      *   - description: shown on the configuration page
    81      *   - classname
    82      * @param array $control_options Optional Passed to wp_register_widget_control()
    83      *   - width: required if more than 250px
    84      *   - height: currently not used but may be needed in the future
     89     * PHP5 constructor.
     90     *
     91     * @since 2.8.0
     92     * @access public
     93     *
     94     * @param string $id_base         Optional Base ID for the widget, lowercase and unique. If left empty,
     95     *                                a portion of the widget's class name will be used Has to be unique.
     96     * @param string $name            Name for the widget displayed on the configuration page.
     97     * @param array  $widget_options  Optional. Widget options. See {@see wp_register_sidebar_widget()} for
     98     *                                information on accepted arguments. Default empty array.
     99     * @param array  $control_options Optional. Widget control options. See {@see wp_register_widget_control()}
     100     *                                for information on accepted arguments. Default empty array.
    85101     */
    86102    public function __construct( $id_base, $name, $widget_options = array(), $control_options = array() ) {
     
    123139    }
    124140
    125     // Private Functions. Don't worry about these.
    126 
     141    /**
     142     * Register all widget instances of this widget class.
     143     *
     144     * @since 2.8.0
     145     * @access private
     146     */
    127147    public function _register() {
    128148        $settings = $this->get_settings();
     
    147167    }
    148168
     169    /**
     170     * Set the internal order number for the widget instance.
     171     *
     172     * @since 2.8.0
     173     * @access private
     174     *
     175     * @param int $number The unique order number of this widget instance compared to other
     176     *                    instances of the same class.
     177     */
    149178    public function _set($number) {
    150179        $this->number = $number;
     
    165194
    166195    /**
    167      * Determine if we're in the Customizer; if true, then the object cache gets
    168      * suspended and widgets should check this to decide whether they should
    169      * store anything persistently to the object cache, to transients, or
    170      * anywhere else.
     196     * Determine whether the current request is inside the Customizer preview.
     197     *
     198     * If true -- the current request is inside the Customizer preview, then
     199     * the object cache gets suspended and widgets should check this to decide
     200     * whether they should store anything persistently to the object cache,
     201     * to transients, or anywhere else.
    171202     *
    172203     * @since 3.9.0
    173      *
    174      * @return bool True if Customizer is on, false if not.
     204     * @access public
     205     *
     206     * @return bool True if within the Customizer preview, false if not.
    175207     */
    176208    public function is_preview() {
     
    179211    }
    180212
    181     /** Generate the actual widget content.
    182      *  Just finds the instance and calls widget().
    183      *  Do NOT over-ride this function. */
     213    /**
     214     * Generate the actual widget content (Do NOT override).
     215     *
     216     * Finds the instance and calls {@see WP_Widget::widget()}.
     217     *
     218     * @access public
     219     *
     220     * @param array     $args        Display arguments. See {@see WP_Widget::widget()} for information
     221     *                               on accepted arguments.
     222     * @param int|array $widget_args {
     223     *     Optional. Internal order number of the widget instance, or array of multi-widget arguments.
     224     *     Default 1.
     225     *
     226     *     @type int $number Number increment used for multiples of the same widget.
     227     * }
     228     */
    184229    public function display_callback( $args, $widget_args = 1 ) {
    185230        if ( is_numeric($widget_args) )
     
    363408    }
    364409
    365     /** Helper function: Registers a single instance. */
    366     public function _register_one($number = -1) {
     410    /**
     411     * Register an instance of the widget class.
     412     *
     413     * @since 2.8.0
     414     * @access private
     415     *
     416     * @param integer $number Optional. The unique order number of this widget instance
     417     *                        compared to other instances of the same class. Default -1.
     418     */
     419    public function _register_one( $number = -1 ) {
    367420        wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
    368421        _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
     
    370423    }
    371424
    372     public function save_settings($settings) {
     425    /**
     426     * Save the settings for all instances of the widget class.
     427     *
     428     * @since 2.8.0
     429     * @access public
     430     *
     431     * @param array $settings Multi-dimensional array of widget instance settings.
     432     */
     433    public function save_settings( $settings ) {
    373434        $settings['_multiwidget'] = 1;
    374435        update_option( $this->option_name, $settings );
    375436    }
    376437
     438    /**
     439     * Get the settings for all instances of the widget class.
     440     *
     441     * @since 2.8.0
     442     * @access public
     443     *
     444     * @return array Multi-dimensional array of widget instance settings.
     445     */
    377446    public function get_settings() {
     447
    378448        $settings = get_option($this->option_name);
    379449
Note: See TracChangeset for help on using the changeset viewer.