Ticket #30315: 30315.diff

wp-includes/widgets.php

@@ -122 +122 @@
                 return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
         }
 
-        // Private Functions. Don't worry about these.
-
+        /**
+         * Register all widget instances of this widget class.
+         *
+         * @access private
+         */
         public function _register() {
                 $settings = $this->get_settings();
                 $empty = true;
@@ -146 +149 @@
                 }
         }
 
+        /**
+         * Set the internal order number for the widget instance.
+         *
+         * @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;
@@ -362 +373 @@
                 return $return;
         }
 
-        /** Helper function: Registers a single instance. */
+        /**
+         * Register an instance of the widget class.
+         *
+         * @access private
+         *
+         * @param  integer $number The unique order number of this widget instance
+         *                         compared to other instances of the same class.
+         */
         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 ) );
         }
 
+        /**
+         * Save the settings for all instances of the widget class.
+         *
+         * @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.
+         *
+         * @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) )
@@ -407 +436 @@
                 add_action( 'widgets_init', array( $this, '_register_widgets' ), 100 );
         }
 
+        /**
+         * Register a widget class.
+         *
+         * @param  mixed $widget_class A subclass of WP_Widget.
+         */
         public function register($widget_class) {
                 $this->widgets[$widget_class] = new $widget_class();
         }
 
+        /**
+         * Unregister a widget class.
+         *
+         * @param  mixed $widget_class A subclass of WP_Widget.
+         */
         public function unregister($widget_class) {
                 if ( isset($this->widgets[$widget_class]) )
                         unset($this->widgets[$widget_class]);
@@ -448 +487 @@
 $wp_registered_sidebars = array();
 
 /**
- * Stores the registered widgets.
+ * Stores instances of widgets.
  *
  * @global array $wp_registered_widgets
  * @since 2.2.0
@@ -683 +722 @@
 }
 
 /**
- * Register widget for use in sidebars.
+ * Register an instance of a widget.
  *
  * The default widget option is 'classname' that can be overridden.
  *
@@ -698 +737 @@
  * @param int|string $id Widget ID.
  * @param string $name Widget display title.
  * @param callback $output_callback Run when widget is called.
- * @param array|string $options Optional. Widget Options.
+ * @param array $options {
+ *     An array of supplementary widget options for the instance. Optional.
+ *
+ *     @type string $classname Classname for the widget's HTML container.
+ *                             Optional. Defaults to the output callback.
+ * }
  * @param mixed $params,... Widget parameters to add to widget.
  * @return null Will return if $output_callback is empty after removing widget.
  */
@@ -1202 +1246 @@
 /* Internal Functions */
 
 /**
- * Retrieve full list of sidebars and their widgets.
+ * Retrieve full list of sidebars and their widget instance IDs.
  *
  * Will upgrade sidebar widget list, if needed. Will also save updated list, if
  * needed.