From 292a65f737cdce041d68e4763520ae1e5f648534 Mon Sep 17 00:00:00 2001
From: "Drew Jaynes (DrewAPicture)" <drewapicture@git.wordpress.org>
Date: Sun, 7 Dec 2014 20:10:37 +0000
Subject: [PATCH] Flesh out information in the DocBlock for
 `wp_register_sidebar_widget()`.

Includes:
* Documenting the `$options` parameter in hash notation style
* Converting `@uses` tags to `@global`
* Various backtick-escaping.

See #30315.


git-svn-id: https://develop.svn.wordpress.org/trunk@30776 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/widgets.php | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/src/wp-includes/widgets.php b/src/wp-includes/widgets.php
index ec0effe6b3..2869ce1b2d 100644
--- a/src/wp-includes/widgets.php
+++ b/src/wp-includes/widgets.php
@@ -849,26 +849,32 @@ function unregister_sidebar( $name ) {
 }
 
 /**
- * Register widget for use in sidebars.
+ * Register an instance of a widget.
  *
  * The default widget option is 'classname' that can be overridden.
  *
- * The function can also be used to un-register widgets when $output_callback
+ * The function can also be used to un-register widgets when `$output_callback`
  * parameter is an empty string.
  *
  * @since 2.2.0
  *
- * @uses $wp_registered_widgets Uses stored registered widgets.
- * @uses $wp_register_widget_defaults Retrieves widget defaults.
+ * @global array $wp_registered_widgets       Uses stored registered widgets.
+ * @global array $wp_register_widget_defaults Retrieves widget defaults.
  *
- * @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 mixed $params,... Widget parameters to add to widget.
- * @return null Will return if $output_callback is empty after removing widget.
+ * @param int|string $id              Widget ID.
+ * @param string     $name            Widget display title.
+ * @param callback   $output_callback Run when widget is called.
+ * @param array      $options {
+ *     Optional. An array of supplementary widget options for the instance.
+ *
+ *     @type string $classname   Class name for the widget's HTML container. Default is a shortened
+ *                               version of the output callback name.
+ *     @type string $description Widget description for display in the widget administration
+ *                               panel and/or theme.
+ * }
+ * @return null Will return if `$output_callback` is empty after removing widget.
  */
-function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
+function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array() ) {
 	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;
 
 	$id = strtolower($id);