diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php
index 791fa165a1..02cbf42067 100644
--- a/wp-includes/widgets.php
+++ b/wp-includes/widgets.php
@@ -1,15 +1,70 @@
'name=whatever;id=whatever1' and for
+ * the array it would be array(
+ * 'name' => 'whatever',
+ * 'id' => 'whatever1')
.
+ *
+ * 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.
+ *
+ * Content 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 @@ function register_sidebar($args = array()) {
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 @@ function unregister_sidebar( $name ) {
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 @@ function register_sidebar_widget($name, $output_callback, $classname = '') {
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 @@ function wp_register_sidebar_widget($id, $name, $output_callback, $options = arr
$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 @@ function wp_widget_description( $id ) {
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 @@ function register_widget_control($name, $control_callback, $width = '', $height
* 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 @@ function wp_register_widget_control($id, $name, $control_callback, $options = ar
$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 @@ function dynamic_sidebar($index = 1) {
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 @@ function is_active_widget($callback, $widget_id = false) {
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 @@ function is_dynamic_sidebar() {
/* 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 @@ function wp_get_sidebars_widgets($update = true) {
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 @@ function wp_get_widget_defaults() {
/* 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 @@ function wp_widget_pages( $args ) {
}
}
+/**
+ * {@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 @@ function wp_widget_pages_control() {
@@ -1046,6 +1486,13 @@ function wp_widget_recent_comments_style() {
'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 @@ function wp_widget_recent_comments_register() {
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 @@ function wp_widget_rss_output( $rss, $args = array() ) {
}
}
+/**
+ * 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 @@ function wp_widget_rss_process( $widget_rss, $check_feed = true ) {
/**
* 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 @@ function wp_widget_rss_register() {
}
/**
- * Display tag cloud WordPress widget.
+ * Display tag cloud widget.
*
- * @since unknown
+ * @since 2.3.0
*
* @param array $args Widget arguments.
*/
@@ -1433,7 +1899,7 @@ function wp_widget_tag_cloud($args) {
*
* 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 @@ function wp_widget_tag_cloud_control() {
* 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() )