Docs: Various Docblock fixes in wp-includes/widgets.php, as per WP Docs standards;

Props ankitpatel1578, sabernhardt.
Fixes #62859.
See #62281.



Built from https://develop.svn.wordpress.org/trunk@59702


git-svn-id: http://core.svn.wordpress.org/trunk@59044 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.8-alpha-59701';
+$wp_version = '6.8-alpha-59702';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/widgets.php

@@ -3,7 +3,7 @@
  * Core Widgets API
  *
  * This API is used for creating dynamic sidebar without hardcoding functionality into
- * themes
+ * themes.
  *
  * Includes both internal WordPress routines and theme-use routines.
  *
@@ -103,7 +103,7 @@ $GLOBALS['_wp_deprecated_widgets_callbacks'] = array(
 //
 
 /**
- * Register a widget
+ * Registers a widget.
  *
  * Registers a WP_Widget widget
  *
@@ -226,7 +226,7 @@ function register_sidebars( $number = 1, $args = array() ) {
  * on what other plugins and themes are installed.
  *
  * If theme support for 'widgets' has not yet been added when this function is
- * called, it will be automatically enabled through the use of add_theme_support()
+ * called, it will be automatically enabled through the use of add_theme_support().
  *
  * @since 2.2.0
  * @since 5.6.0 Added the `before_sidebar` and `after_sidebar` arguments.
@@ -361,7 +361,7 @@ function is_registered_sidebar( $sidebar_id ) {
 }
 
 /**
- * Register an instance of a widget.
+ * Registers an instance of a widget.
  *
  * The default widget option is 'classname' that can be overridden.
  *
@@ -435,7 +435,7 @@ function wp_register_sidebar_widget( $id, $name, $output_callback, $options = ar
 }
 
 /**
- * Retrieve description for widget.
+ * Retrieves description for widget.
  *
  * When registering widgets, the options can also include 'description' that
  * describes the widget for display on the widget administration panel or
@@ -461,7 +461,7 @@ function wp_widget_description( $id ) {
 }
 
 /**
- * Retrieve description for a sidebar.
+ * Retrieves description for a sidebar.
  *
  * When registering sidebars a 'description' parameter can be included that
  * describes the sidebar for display on the widget administration panel.
@@ -669,7 +669,7 @@ function _register_widget_form_callback( $id, $name, $form_callback, $options =
 }
 
 /**
- * Remove control callback for widget.
+ * Removes control callback for widget.
  *
  * @since 2.2.0
  *
@@ -680,7 +680,7 @@ function wp_unregister_widget_control( $id ) {
 }
 
 /**
- * Display dynamic sidebar.
+ * Displays dynamic sidebar.
  *
  * By default this displays the default sidebar or 'sidebar-1'. If your theme specifies the 'id' or
  * 'name' parameter for its registered sidebars you can pass an ID or name as the $index parameter.
@@ -883,8 +883,8 @@ function dynamic_sidebar( $index = 1 ) {
 /**
  * Determines whether a given widget is displayed on the front end.
  *
- * Either $callback or $id_base can be used
- * $id_base is the first argument when extending WP_Widget class
+ * Either $callback or $id_base can be used.
+ * $id_base is the first argument when extending WP_Widget class.
  * Without the optional $widget_id parameter, returns the ID of the first sidebar
  * in which the first instance of the widget with the given callback or $id_base is found.
  * With the $widget_id parameter, returns the ID of the sidebar where
@@ -1002,7 +1002,7 @@ function is_active_sidebar( $index ) {
 //
 
 /**
- * Retrieve full list of sidebars and their widget instance IDs.
+ * Retrieves the full list of sidebars and their widget instance IDs.
  *
  * Will upgrade sidebar widget list, if needed. Will also save updated list, if
  * needed.
@@ -1081,7 +1081,7 @@ function wp_get_sidebar( $id ) {
 }
 
 /**
- * Set the sidebar widget option to update sidebars.
+ * Sets the sidebar widget option to update sidebars.
  *
  * @since 2.2.0
  * @access private
@@ -1103,7 +1103,7 @@ function wp_set_sidebars_widgets( $sidebars_widgets ) {
 }
 
 /**
- * Retrieve default registered sidebars list.
+ * Retrieves default registered sidebars list.
  *
  * @since 2.2.0
  * @access private
@@ -1194,7 +1194,7 @@ function wp_convert_widget_settings( $base_name, $option_name, $settings ) {
 }
 
 /**
- * Output an arbitrary widget as a template tag.
+ * Outputs an arbitrary widget as a template tag.
  *
  * @since 2.8.0
  *
@@ -1282,7 +1282,7 @@ function _get_widget_id_base( $id ) {
 }
 
 /**
- * Handle sidebars config after theme change
+ * Handles sidebars config after theme change.
  *
  * @access private
  * @since 3.3.0
@@ -1575,7 +1575,7 @@ function _wp_remove_unregistered_widgets( $sidebars_widgets, $allowed_widget_ids
 }
 
 /**
- * Display the RSS entries in a list.
+ * Displays the RSS entries in a list.
  *
  * @since 2.5.0
  *
@@ -1682,7 +1682,7 @@ function wp_widget_rss_output( $rss, $args = array() ) {
 }
 
 /**
- * Display RSS widget options form.
+ * Displays RSS widget options form.
  *
  * The options for what fields are displayed for the RSS form are all booleans
  * and are as follows: 'url', 'title', 'items', 'show_summary', 'show_author',
@@ -1763,7 +1763,7 @@ foreach ( array_keys( $default_inputs ) as $input ) :
 }
 
 /**
- * Process RSS feed widget data and optionally retrieve feed items.
+ * Processes RSS feed widget data and optionally retrieve feed items.
  *
  * The feed widget can not have more than 20 items or it will reset back to the
  * default, which is 10.
@@ -1883,9 +1883,9 @@ function wp_setup_widgets_block_editor() {
 }
 
 /**
- * Whether or not to use the block editor to manage widgets. Defaults to true
- * unless a theme has removed support for widgets-block-editor or a plugin has
- * filtered the return value of this function.
+ * Determines whether or not to use the block editor to manage widgets.
+ * Defaults to true unless a theme has removed support for widgets-block-editor
+ * or a plugin has filtered the return value of this function.
  *
  * @since 5.8.0
  *