Index: widgets.php
===================================================================
--- widgets.php	(revision 8934)
+++ widgets.php	(working copy)
@@ -1,15 +1,70 @@
 <?php
+/**
+ * API for creating dynamic sidebar without hardcoding functionality into
+ * themes. Includes both internal WordPress routines and theme use routines.
+ *
+ * This functionality was found in a plugin before WordPress 2.2 release which
+ * included it in the core from that point on.
+ *
+ * @link http://codex.wordpress.org/Plugins/WordPress_Widgets WordPress Widgets
+ * @link http://codex.wordpress.org/Plugins/WordPress_Widgets_Api Widgets API
+ *
+ * @package WordPress
+ * @subpackage Widgets
+ */
 
 /* Global Variables */
 
+/** @ignore */
 global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls;
 
+/**
+ * Stores the sidebars, since many themes can have more than one.
+ *
+ * @global array $wp_registered_sidebars
+ * @since 2.2.0
+ */
 $wp_registered_sidebars = array();
+
+/**
+ * Stores the registered widgets.
+ *
+ * @global array $wp_registered_widgets
+ * @since 2.2.0
+ */
 $wp_registered_widgets = array();
+
+/**
+ *
+ * @global array $wp_registered_widget_controls
+ * @since 2.2.0
+ */
 $wp_registered_widget_controls = array();
 
 /* Template tags & API functions */
 
+/**
+ * Creates multiple sidebars.
+ *
+ * If you wanted to quickly create multiple sidebars for a theme or internally.
+ * This function will allow you to do so. If you don't pass the 'name' and/or
+ * 'id' in $args, then they will be built for you.
+ *
+ * The default for the name is "Sidebar #", with '#' being replaced with the
+ * number the sidebar is currently when greater than one. If first sidebar, the
+ * name will be just "Sidebar". The default for id is "sidebar-" followed by the
+ * number the sidebar creation is currently at.
+ *
+ * @since 2.2.0
+ *
+ * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
+ * @uses parse_str() Converts a string to an array to be used in the rest of the function.
+ * @uses register_sidebar() Sends single sidebar information [name, id] to this
+ *	function to handle building the sidebar.
+ *
+ * @param int $number Number of sidebars to create.
+ * @param string|array $args Builds Sidebar based off of 'name' and 'id' values.
+ */
 function register_sidebars($number = 1, $args = array()) {
 	global $wp_registered_sidebars;
 	$number = (int) $number;
@@ -40,6 +95,40 @@
 	}
 }
 
+/**
+ * Builds the definition for a single sidebar and returns the ID.
+ *
+ * The $args parameter takes either a string or an array with 'name' and 'id'
+ * contained in either usage. It will be noted that the values will be applied
+ * to all sidebars, so if creating more than one, it will be advised to allow
+ * for WordPress to create the defaults for you.
+ *
+ * Example for string would be <code>'name=whatever;id=whatever1'</code> and for
+ * the array it would be <code>array(
+ *    'name' => 'whatever',
+ *    'id' => 'whatever1')</code>.
+ *
+ * name - The name of the sidebar, which presumably the title which will be
+ *     displayed.
+ * id - The unique identifier by which the sidebar will be called by.
+ * before_widget - The content that will prepended to the widgets when they are
+ *     displayed.
+ * after_widget - The content that will be appended to the widgets when they are
+ *     displayed.
+ * before_title - The content that will be prepended to the title when displayed.
+ * after_title - the content that will be appended to the title when displayed.
+ *
+ * <em>Content</em> is assumed to be HTML and should be formatted as such, but
+ * doesn't have to be.
+ *
+ * @since 2.2.0
+ * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
+ * @uses parse_str() Converts a string to an array to be used in the rest of the function.
+ * @usedby register_sidebars()
+ *
+ * @param string|array $args Builds Sidebar based off of 'name' and 'id' values
+ * @return string The sidebar id that was added.
+ */
 function register_sidebar($args = array()) {
 	global $wp_registered_sidebars;
 
@@ -64,6 +153,15 @@
 	return $sidebar['id'];
 }
 
+/**
+ * Removes a sidebar from the list.
+ *
+ * @since 2.2.0
+ *
+ * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
+ *
+ * @param string $name The ID of the sidebar when it was added.
+ */
 function unregister_sidebar( $name ) {
 	global $wp_registered_sidebars;
 
@@ -71,6 +169,18 @@
 		unset( $wp_registered_sidebars[$name] );
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ * @uses wp_register_sidebar_widget() Passes the compiled arguments.
+ *
+ * @param string $name 
+ * @param callback $output_callback
+ * @param string $classname
+ */
 function register_sidebar_widget($name, $output_callback, $classname = '') {
 	// Compat
 	if ( is_array($name) ) {
@@ -92,6 +202,22 @@
 	call_user_func_array('wp_register_sidebar_widget', $args);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @uses $wp_registered_widgets {@internal Missing Description}}
+ * @uses $wp_register_widget_defaults {@internal Missing Description}}
+ *
+ * @param int $id {@internal Missing Description}}
+ * @param string $name {@internal Missing Description}}
+ * @param callback $output_callback {@internal Missing Description}}
+ * @param array|string $options {@internal Missing Description}}
+ * @return null Will return if $output_callback is empty
+ */
 function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
 	global $wp_registered_widgets;
 
@@ -116,6 +242,16 @@
 		$wp_registered_widgets[$id] = $widget;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.5.0
+ *
+ * @param unknown_type $id
+ * @return unknown
+ */
 function wp_widget_description( $id ) {
 	if ( !is_scalar($id) )
 		return;
@@ -126,15 +262,45 @@
 		return wp_specialchars( $wp_registered_widgets[$id]['description'] );
 }
 
+/**
+ * Alias of {@link wp_unregister_sidebar_widget()}.
+ *
+ * @see wp_unregister_sidebar_widget()
+ *
+ * @since 2.2.0
+ *
+ * @param int $id Same as wp_unregister_sidebar_widget()
+ */
 function unregister_sidebar_widget($id) {
 	return wp_unregister_sidebar_widget($id);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param int $id {@internal Missing Description}}
+ */
 function wp_unregister_sidebar_widget($id) {
 	wp_register_sidebar_widget($id, '', '');
 	wp_unregister_widget_control($id);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $name {@internal Missing Description}}
+ * @param unknown_type $control_callback {@internal Missing Description}}
+ * @param unknown_type $width {@internal Missing Description}}
+ * @param unknown_type $height {@internal Missing Description}}
+ */
 function register_widget_control($name, $control_callback, $width = '', $height = '') {
 	// Compat
 	if ( is_array($name) ) {
@@ -164,6 +330,18 @@
  *   id_base: for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided.
  *            the widget id will ennd up looking like {$id_base}-{$unique_number}
  */
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param int $id {@internal Missing Description}}
+ * @param string $name {@internal Missing Description}}
+ * @param callback $control_callback {@internal Missing Description}}
+ * @param array|string $options {@internal Missing Description}}
+ */
 function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
 	global $wp_registered_widget_controls;
 
@@ -193,14 +371,42 @@
 	$wp_registered_widget_controls[$id] = $widget;
 }
 
+/**
+ * Alias of {@link wp_unregister_widget_control()}.
+ *
+ * @since 2.2.0
+ * @see wp_unregister_widget_control()
+ *
+ * @param int $id Widget ID
+ */
 function unregister_widget_control($id) {
 	return wp_unregister_widget_control($id);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ * @uses wp_register_widget_control() {@internal Missing Description}}
+ *
+ * @param int $id {@internal Missing Description}}
+ */
 function wp_unregister_widget_control($id) {
 	return wp_register_widget_control($id, '', '');
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $index
+ * @return unknown
+ */
 function dynamic_sidebar($index = 1) {
 	global $wp_registered_sidebars, $wp_registered_widgets;
 
@@ -254,6 +460,14 @@
 	return $did_one;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $callback
 /* @return mixed false if widget is not active or id of sidebar in which the widget is active
  */
 function is_active_widget($callback, $widget_id = false) {
@@ -271,6 +485,15 @@
 	return false;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @return unknown
+ */
 function is_dynamic_sidebar() {
 	global $wp_registered_widgets, $wp_registered_sidebars;
 	$sidebars_widgets = get_option('sidebars_widgets');
@@ -286,6 +509,17 @@
 
 /* Internal Functions */
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ * @access private
+ *
+ * @param unknown_type $update
+ * @return unknown
+ */
 function wp_get_sidebars_widgets($update = true) {
 	global $wp_registered_widgets, $wp_registered_sidebars;
 
@@ -364,10 +598,31 @@
 	return $sidebars_widgets;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ * @access private
+ * @uses update_option() 
+ *
+ * @param unknown_type $sidebars_widgets
+ */
 function wp_set_sidebars_widgets( $sidebars_widgets ) {
 	update_option( 'sidebars_widgets', $sidebars_widgets );
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ * @access private
+ *
+ * @return unknown
+ */
 function wp_get_widget_defaults() {
 	global $wp_registered_sidebars;
 
@@ -381,6 +636,15 @@
 
 /* Default Widgets */
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ */
 function wp_widget_pages( $args ) {
 	extract( $args );
 	$options = get_option( 'widget_pages' );
@@ -407,6 +671,13 @@
 	}
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_pages_control() {
 	$options = $newoptions = get_option('widget_pages');
 	if ( $_POST['pages-submit'] ) {
@@ -448,6 +719,15 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ */
 function wp_widget_links($args) {
 	extract($args, EXTR_SKIP);
 
@@ -459,6 +739,15 @@
 	)));
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ */
 function wp_widget_search($args) {
 	extract($args);
 	$searchform_template = get_template_directory() . '/searchform.php';
@@ -479,6 +768,15 @@
 	echo $after_widget;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ */
 function wp_widget_archives($args) {
 	extract($args);
 	$options = get_option('widget_archives');
@@ -504,6 +802,13 @@
 	echo $after_widget;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_archives_control() {
 	$options = $newoptions = get_option('widget_archives');
 	if ( $_POST["archives-submit"] ) {
@@ -529,6 +834,15 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget Arguments
+ */
 function wp_widget_meta($args) {
 	extract($args);
 	$options = get_option('widget_meta');
@@ -547,6 +861,14 @@
 		<?php echo $after_widget; ?>
 <?php
 }
+
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_meta_control() {
 	$options = $newoptions = get_option('widget_meta');
 	if ( $_POST["meta-submit"] ) {
@@ -563,6 +885,15 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ */
 function wp_widget_calendar($args) {
 	extract($args);
 	$options = get_option('widget_calendar');
@@ -576,6 +907,13 @@
 	echo $after_widget;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_calendar_control() {
 	$options = $newoptions = get_option('widget_calendar');
 	if ( $_POST["calendar-submit"] ) {
@@ -592,7 +930,19 @@
 <?php
 }
 
-// See large comment section at end of this file
+/**
+ * Display the Text widget, depending on the widget number.
+ *
+ * Supports multiple text widgets and keeps track of the widget number by using
+ * the $widget_args parameter. The option 'widget_text' is used to store the
+ * content for the widgets. The content and title are passed through the
+ * 'widget_text' and 'widget_title' filters respectively.
+ *
+ * @since 2.2.0
+ *
+ * @param array $args Widget arguments.
+ * @param int $number Widget number.
+ */
 function wp_widget_text($args, $widget_args = 1) {
 	extract( $args, EXTR_SKIP );
 	if ( is_numeric($widget_args) )
@@ -614,6 +964,15 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param int $widget_args Widget number.
+ */
 function wp_widget_text_control($widget_args) {
 	global $wp_registered_widgets;
 	static $updated = false;
@@ -676,6 +1035,13 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_text_register() {
 	if ( !$options = get_option('widget_text') )
 		$options = array();
@@ -700,6 +1066,16 @@
 	}
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ * @param unknown_type $number
+ */
 // See large comment section at end of this file
 function wp_widget_categories($args, $widget_args = 1) {
 	extract($args, EXTR_SKIP);
@@ -755,6 +1131,15 @@
 	echo $after_widget;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $number
+ */
 function wp_widget_categories_control( $widget_args ) {
 	global $wp_registered_widgets;
 	static $updated = false;
@@ -841,6 +1226,13 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ */
 function wp_widget_categories_register() {
 	if ( !$options = get_option( 'widget_categories' ) )
 		$options = array();
@@ -869,6 +1261,15 @@
 	}
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @return unknown
+ */
 function wp_widget_categories_upgrade() {
 	$options = get_option( 'widget_categories' );
 
@@ -896,6 +1297,16 @@
 	return $newoptions;
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ * @return unknown
+ */
 function wp_widget_recent_entries($args) {
 	if ( '%BEG_OF_TITLE%' != $args['before_title'] ) {
 		if ( $output = wp_cache_get('widget_recent_entries', 'widget') )
@@ -935,7 +1346,9 @@
 /**
  * Remove recent entries widget items cache.
  *
- * @since unknown
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
  */
 function wp_flush_widget_recent_entries() {
 	wp_cache_delete('widget_recent_entries', 'widget');
@@ -945,6 +1358,13 @@
 add_action('deleted_post', 'wp_flush_widget_recent_entries');
 add_action('switch_theme', 'wp_flush_widget_recent_entries');
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_recent_entries_control() {
 	$options = $newoptions = get_option('widget_recent_entries');
 	if ( $_POST["recent-entries-submit"] ) {
@@ -971,6 +1391,15 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_recent_comments($args) {
 	global $wpdb, $comments, $comment;
 	extract($args, EXTR_SKIP);
@@ -1002,7 +1431,9 @@
 /**
  * Remove the cache for recent comments widget.
  *
- * @since unknown
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
  */
 function wp_delete_recent_comments_cache() {
 	wp_cache_delete( 'recent_comments', 'widget' );
@@ -1010,6 +1441,13 @@
 add_action( 'comment_post', 'wp_delete_recent_comments_cache' );
 add_action( 'wp_set_comment_status', 'wp_delete_recent_comments_cache' );
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_recent_comments_control() {
 	$options = $newoptions = get_option('widget_recent_comments');
 	if ( $_POST["recent-comments-submit"] ) {
@@ -1038,7 +1476,9 @@
 /**
  * Display the style for recent comments widget.
  *
- * @since unknown
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
  */
 function wp_widget_recent_comments_style() {
 ?>
@@ -1046,6 +1486,13 @@
 <?php
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_recent_comments_register() {
 	$widget_ops = array('classname' => 'widget_recent_comments', 'description' => __( 'The most recent comments' ) );
 	wp_register_sidebar_widget('recent-comments', __('Recent Comments'), 'wp_widget_recent_comments', $widget_ops);
@@ -1055,6 +1502,16 @@
 		add_action('wp_head', 'wp_widget_recent_comments_style');
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ * @param unknown_type $number
+ */
 // See large comment section at end of this file
 function wp_widget_rss($args, $widget_args = 1) {
 	extract($args, EXTR_SKIP);
@@ -1190,6 +1647,15 @@
 	}
 }
 
+/**
+ * wp_widget_rss_control() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $widget_args
+ */
 function wp_widget_rss_control($widget_args) {
 	global $wp_registered_widgets;
 	static $updated = false;
@@ -1384,7 +1850,7 @@
 /**
  * Register RSS widget to allow multiple RSS widgets.
  *
- * @since unknown
+ * @since 2.2.0
  */
 function wp_widget_rss_register() {
 	if ( !$options = get_option('widget_rss') )
@@ -1411,9 +1877,9 @@
 }
 
 /**
- * Display tag cloud WordPress widget.
+ * Display tag cloud widget.
  *
- * @since unknown
+ * @since 2.3.0
  *
  * @param array $args Widget arguments.
  */
@@ -1433,7 +1899,7 @@
  *
  * Displays management form for changing the tag cloud widget title.
  *
- * @since unknown
+ * @since 2.3.0
  */
 function wp_widget_tag_cloud_control() {
 	$options = $newoptions = get_option('widget_tag_cloud');
@@ -1462,7 +1928,7 @@
  * Calls 'widgets_init' action after all of the WordPress widgets have been
  * registered.
  *
- * @since unknown
+ * @since 2.2.0
  */
 function wp_widgets_init() {
 	if ( !is_blog_installed() )