Index: wp-includes/widgets.php
===================================================================
--- wp-includes/widgets.php	(revision 30365)
+++ wp-includes/widgets.php	(working copy)
@@ -25,19 +25,22 @@
 
 	public $id_base;			// Root id for all widgets of this type.
 	public $name;				// Name for this widget type.
-	public $widget_options;	// Option array passed to wp_register_sidebar_widget()
+	public $widget_options;	    // Option array passed to wp_register_sidebar_widget()
 	public $control_options;	// Option array passed to wp_register_widget_control()
 
-	public $number = false;	// Unique ID number of the current instance.
-	public $id = false;		// Unique ID string of the current instance (id_base-number)
+	public $number = false;	    // Unique ID number of the current instance.
+	public $id = false;		    // Unique ID string of the current instance (id_base-number)
 	public $updated = false;	// Set true when we update the data after a POST submit - makes sure we don't do it twice.
 
 	// 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.
 	 *
+	 * @since 2.8.0
+	 *
 	 * @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
 	 */
@@ -45,12 +48,15 @@
 		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.
 	 *
+	 * @since 2.8.0
+	 *
 	 * @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
@@ -59,8 +65,11 @@
 		return $new_instance;
 	}
 
-	/** Echo the settings update form
+	/**
+	 * Echo the settings update form
 	 *
+	 * @since 2.8.0
+	 *
 	 * @param array $instance Current settings
 	 */
 	public function form($instance) {
@@ -122,8 +131,13 @@
 		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 +160,16 @@
 		}
 	}
 
+	/**
+	 * 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;
@@ -362,19 +386,43 @@
 		return $return;
 	}
 
-	/** Helper function: Registers a single instance. */
+	/**
+	 * Register an instance of the widget class.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @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.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @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
+	 *
+	 * @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,10 +455,24 @@
 		add_action( 'widgets_init', array( $this, '_register_widgets' ), 100 );
 	}
 
+	/**
+	 * Register a widget class.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @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.
+	 *
+	 * @since 2.8.0
+	 *
+	 * @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,7 +510,7 @@
 $wp_registered_sidebars = array();
 
 /**
- * Stores the registered widgets.
+ * Stores instances of widgets.
  *
  * @global array $wp_registered_widgets
  * @since 2.2.0
@@ -683,7 +745,7 @@
 }
 
 /**
- * Register widget for use in sidebars.
+ * Register an instance of a widget.
  *
  * The default widget option is 'classname' that can be overridden.
  *
@@ -698,7 +760,12 @@
  * @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,7 +1269,7 @@
 /* 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.