Index: widgets.php
===================================================================
--- widgets.php	(revision 8786)
+++ widgets.php	(working copy)
@@ -1,15 +1,64 @@
 <?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.
+ *
+ * @package WordPress
+ * @subpackage Widgets
+ */
 
 /* Global Variables */
 
 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
+ */
 $wp_registered_sidebars = array();
+
+/**
+ *
+ * @global array $wp_registered_widgets
+ * @since 2.2
+ */
 $wp_registered_widgets = array();
+
+/**
+ *
+ * @global array $wp_registered_widget_controls
+ * @since 2.2
+ */
 $wp_registered_widget_controls = array();
 
 /* Template tags & API functions */
 
+/**
+ * register_sidebars() - 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.
+ *
+ * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
+ *
+ * @since 2.2
+ *
+ * @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 +89,33 @@
 	}
 }
 
+/**
+ * register_sidebar() - 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
+ * @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 +140,15 @@
 	return $sidebar['id'];
 }
 
+/**
+ * unregister_sidebar() - 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 +156,18 @@
 		unset( $wp_registered_sidebars[$name] );
 }
 
+/**
+ * register_sidebar_widget() - {@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 +189,22 @@
 	call_user_func_array('wp_register_sidebar_widget', $args);
 }
 
+/**
+ * wp_register_sidebar_widget() - {@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 +229,16 @@
 		$wp_registered_widgets[$id] = $widget;
 }
 
+/**
+ * wp_widget_description() - {@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 +249,45 @@
 		return wp_specialchars( $wp_registered_widgets[$id]['description'] );
 }
 
+/**
+ * unregister_sidebar_widget() - Alias of 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);
 }
 
+/**
+ * wp_register_sidebar_widget() - {@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);
 }
 
+/**
+ * register_widget_control() - {@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 +317,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}
  */
+/**
+ * wp_register_widget_control() - {@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 +358,42 @@
 	$wp_registered_widget_controls[$id] = $widget;
 }
 
+/**
+ * unregister_widget_control() - Alias of 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);
 }
 
+/**
+ * wp_unregister_widget_control() - {@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, '', '');
 }
 
+/**
+ * dynamic_sidebar() - {@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 +447,14 @@
 	return $did_one;
 }
 
+/**
+ * is_active_widget() - {@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 +472,15 @@
 	return false;
 }
 
+/**
+ * is_dynamic_sidebar() - {@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 +496,17 @@
 
 /* Internal Functions */
 
+/**
+ * wp_get_sidebars_widgets() - {@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 +585,31 @@
 	return $sidebars_widgets;
 }
 
+/**
+ * wp_set_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 );
 }
 
+/**
+ * wp_get_widget_defaults() - {@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 +623,15 @@
 
 /* Default Widgets */
 
+/**
+ * wp_widget_pages() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_pages( $args ) {
 	extract( $args );
 	$options = get_option( 'widget_pages' );
@@ -407,6 +658,13 @@
 	}
 }
 
+/**
+ * wp_widget_pages_control() - {@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 +706,15 @@
 <?php
 }
 
+/**
+ * wp_widget_links() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_links($args) {
 	extract($args, EXTR_SKIP);
 
@@ -459,6 +726,15 @@
 	)));
 }
 
+/**
+ * wp_widget_search() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_search($args) {
 	extract($args);
 	$searchform_template = get_template_directory() . '/searchform.php';
@@ -479,6 +755,15 @@
 	echo $after_widget;
 }
 
+/**
+ * wp_widget_archives() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_archives($args) {
 	extract($args);
 	$options = get_option('widget_archives');
@@ -504,6 +789,13 @@
 	echo $after_widget;
 }
 
+/**
+ * wp_widget_archives_control() - {@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 +821,15 @@
 <?php
 }
 
+/**
+ * wp_widget_meta() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_meta($args) {
 	extract($args);
 	$options = get_option('widget_meta');
@@ -547,6 +848,14 @@
 		<?php echo $after_widget; ?>
 <?php
 }
+
+/**
+ * wp_widget_meta_control() - {@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 +872,15 @@
 <?php
 }
 
+/**
+ * wp_widget_calendar() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_calendar($args) {
 	extract($args);
 	$options = get_option('widget_calendar');
@@ -575,6 +893,14 @@
 	echo '</div>';
 	echo $after_widget;
 }
+
+/**
+ * wp_widget_calendar_control() - {@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"] ) {
@@ -591,6 +917,16 @@
 <?php
 }
 
+/**
+ * wp_widget_text() - {@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_text($args, $widget_args = 1) {
 	extract( $args, EXTR_SKIP );
@@ -613,6 +949,15 @@
 <?php
 }
 
+/**
+ * wp_widget_text_control() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ *
+ * @param unknown_type $number
+ */
 function wp_widget_text_control($widget_args) {
 	global $wp_registered_widgets;
 	static $updated = false;
@@ -675,6 +1020,13 @@
 <?php
 }
 
+/**
+ * wp_widget_text_register() - {@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();
@@ -699,6 +1051,16 @@
 	}
 }
 
+/**
+ * wp_widget_categories() - {@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);
@@ -754,6 +1116,15 @@
 	echo $after_widget;
 }
 
+/**
+ * wp_widget_categories_control() - {@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;
@@ -840,6 +1211,13 @@
 <?php
 }
 
+/**
+ * wp_widget_categories_register() - {@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();
@@ -868,6 +1246,15 @@
 	}
 }
 
+/**
+ * wp_widget_categories_upgrade() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @return unknown
+ */
 function wp_widget_categories_upgrade() {
 	$options = get_option( 'widget_categories' );
 
@@ -895,6 +1282,16 @@
 	return $newoptions;
 }
 
+/**
+ * wp_widget_recent_entries() - {@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') )
@@ -931,6 +1328,13 @@
 		wp_cache_add('widget_recent_entries', ob_get_flush(), 'widget');
 }
 
+/**
+ * wp_flush_widget_recent_entries() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_flush_widget_recent_entries() {
 	wp_cache_delete('widget_recent_entries', 'widget');
 }
@@ -939,6 +1343,13 @@
 add_action('deleted_post', 'wp_flush_widget_recent_entries');
 add_action('switch_theme', 'wp_flush_widget_recent_entries');
 
+/**
+ * wp_widget_recent_entries_control() - {@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"] ) {
@@ -965,6 +1376,15 @@
 <?php
 }
 
+/**
+ * wp_widget_recent_comments() - {@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);
@@ -993,12 +1413,26 @@
 <?php
 }
 
+/**
+ * wp_delete_recent_comments_cache() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_delete_recent_comments_cache() {
 	wp_cache_delete( 'recent_comments', 'widget' );
 }
 add_action( 'comment_post', 'wp_delete_recent_comments_cache' );
 add_action( 'wp_set_comment_status', 'wp_delete_recent_comments_cache' );
 
+/**
+ * wp_widget_recent_comments_control() - {@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"] ) {
@@ -1024,12 +1458,26 @@
 <?php
 }
 
+/**
+ * wp_widget_recent_comments_style() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_recent_comments_style() {
 ?>
 <style type="text/css">.recentcomments a{display:inline !important;padding: 0 !important;margin: 0 !important;}</style>
 <?php
 }
 
+/**
+ * wp_widget_recent_comments_register() - {@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);
@@ -1039,6 +1487,16 @@
 		add_action('wp_head', 'wp_widget_recent_comments_style');
 }
 
+/**
+ * wp_widget_rss() - {@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);
@@ -1174,6 +1632,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;
@@ -1338,6 +1805,13 @@
 	return compact( 'title', 'url', 'link', 'items', 'error', 'show_summary', 'show_author', 'show_date' );
 }
 
+/**
+ * wp_widget_rss_register() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widget_rss_register() {
 	if ( !$options = get_option('widget_rss') )
 		$options = array();
@@ -1362,6 +1836,15 @@
 	}
 }
 
+/**
+ * wp_widget_tag_cloud() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ *
+ * @param unknown_type $args
+ */
 function wp_widget_tag_cloud($args) {
 	extract($args);
 	$options = get_option('widget_tag_cloud');
@@ -1373,6 +1856,13 @@
 	echo $after_widget;
 }
 
+/**
+ * wp_widget_tag_cloud_control() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.3.0
+ */
 function wp_widget_tag_cloud_control() {
 	$options = $newoptions = get_option('widget_tag_cloud');
 
@@ -1394,6 +1884,13 @@
 <?php
 }
 
+/**
+ * wp_widgets_init() - {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since 2.2.0
+ */
 function wp_widgets_init() {
 	if ( !is_blog_installed() )
 		return;