Ticket #7661: 7661.r8954.diff

widgets.php

@@ -324 +324 @@
         call_user_func_array('wp_register_widget_control', $args);
 }
 
-/* $options: height, width, id_base
- *   height: never used
- *   width:  width of fully expanded control form.  Try hard to use the default width.
- *   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}}
  *
+ * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
+ * option is never used. The 'width' option is the width of the fully expanded
+ * control form, but try hard to use the default width. The 'id_base' is for
+ * multi-widgets (widgets which allow multiple instances such as the text
+ * widget), an id_base must be provided. The widget id will end up looking like
+ * {$id_base}-{$unique_number}.
+ *
  * @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}}
+ * @param int|string $id Sidebar ID.
+ * @param string $name Sidebar display name.
+ * @param callback $control_callback Run when sidebar is displayed.
+ * @param array|string $options Optional. Widget options. See above long description.
+ * @param mixed $params,... Optional. Additional parameters to add to widget.
  */
 function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
         global $wp_registered_widget_controls;
@@ -398 +400 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Display dynamic sidebar.
  *
  * {@internal Missing Long Description}}
  *
  * @since 2.2.0
  *
- * @param unknown_type $index
- * @return unknown
+ * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.
+ * @return bool True, if widget sidebar was found and called. False if not found or not called.
  */
 function dynamic_sidebar($index = 1) {
         global $wp_registered_sidebars, $wp_registered_widgets;
@@ -461 +463 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Whether widget is registered using callback with widget ID.
  *
- * {@internal Missing Long Description}}
+ * Will only check if both parameters are used. Used to find which sidebar the
+ * widget is located in, but requires that both the callback and the widget ID
+ * be known.
  *
  * @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
+ * @param callback $callback Widget callback to check.
+ * @param int $widget_id Optional, but needed for checking. Widget ID.
+/* @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) {
         global $wp_registered_widgets;
@@ -486 +491 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Whether the dynamic sidebar is enabled and used by theme.
  *
- * {@internal Missing Long Description}}
- *
  * @since 2.2.0
  *
- * @return unknown
+ * @return bool True, if using widgets. False, if not using widgets.
  */
 function is_dynamic_sidebar() {
         global $wp_registered_widgets, $wp_registered_sidebars;
@@ -510 +513 @@
 /* Internal Functions */
 
 /**
- * {@internal Missing Short Description}}
+ * Retrieve full list of sidebars and their widgets.
  *
- * {@internal Missing Long Description}}
+ * Will upgrade sidebar widget list, if needed. Will also save updated list, if
+ * needed.
  *
  * @since 2.2.0
  * @access private
  *
- * @param unknown_type $update
- * @return unknown
+ * @param bool $update Optional, default is true. Whether to save upgrade of widget array list.
+ * @return array Upgraded list of widgets to version 2 array format.
  */
 function wp_get_sidebars_widgets($update = true) {
         global $wp_registered_widgets, $wp_registered_sidebars;
@@ -599 +603 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Set the sidebar widget option to update sidebars.
  *
- * {@internal Missing Long Description}}
- *
  * @since 2.2.0
  * @access private
- * @uses update_option() 
  *
- * @param unknown_type $sidebars_widgets
+ * @param array $sidebars_widgets Sidebar widgets and their settings.
  */
 function wp_set_sidebars_widgets( $sidebars_widgets ) {
         update_option( 'sidebars_widgets', $sidebars_widgets );
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Retrieve default registered sidebars list.
  *
- * {@internal Missing Long Description}}
- *
  * @since 2.2.0
  * @access private
  *
- * @return unknown
+ * @return array
  */
 function wp_get_widget_defaults() {
         global $wp_registered_sidebars;