Docs: Various formatting improvements to inline docblocks.

See #49572

git-svn-id: https://develop.svn.wordpress.org/trunk@48574 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/includes/class-wp-debug-data.php

@@ -1299,8 +1299,8 @@ class WP_Debug_Data {
 	 *
 	 * @since 5.2.0
 	 *
-	 * @param array $info_array Information gathered from the `WP_Debug_Data::debug_data` function.
+	 * @param array  $info_array Information gathered from the `WP_Debug_Data::debug_data` function.
-	 * @param string $type      The data type to return, either 'info' or 'debug'.
+	 * @param string $type       The data type to return, either 'info' or 'debug'.
 	 * @return string The formatted data.
 	 */
 	public static function format( $info_array, $type ) {

src/wp-admin/includes/class-wp-screen.php

@@ -467,7 +467,7 @@ final class WP_Screen {
 	 * @since 3.3.0
 	 *
 	 * @param WP_Screen $screen A screen object.
-	 * @param string $help Help text.
+	 * @param string    $help   Help text.
 	 */
 	public static function add_old_compat_help( $screen, $help ) {
 		self::$_old_compat_help[ $screen->id ] = $help;
@@ -496,8 +496,8 @@ final class WP_Screen {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param string $option Option ID
+	 * @param string $option Option ID.
-	 * @param mixed $args Option-dependent arguments.
+	 * @param mixed  $args   Option-dependent arguments.
 	 */
 	public function add_option( $option, $args = array() ) {
 		$this->_options[ $option ] = $args;

src/wp-admin/includes/image.php

@@ -7,7 +7,7 @@
  */
 
 /**
- * Crop an Image to a given size.
+ * Crops an image to a given size.
  *
  * @since 2.1.0
  *

src/wp-admin/includes/list-table.php

@@ -70,7 +70,7 @@ function _get_list_table( $class, $args = array() ) {
  *
  * @since 2.7.0
  *
- * @param string  $screen   The handle for the screen to add help to. This is usually the hook name returned by the
+ * @param string   $screen  The handle for the screen to add help to. This is usually the hook name returned by the
  *                          add_*_page() functions.
  * @param string[] $columns An array of columns with column IDs as the keys and translated column names as the values.
  */

src/wp-admin/includes/meta-boxes.php

@@ -17,8 +17,8 @@
  *
  * @global string $action
  *
- * @param WP_Post  $post Current post object.
+ * @param WP_Post $post Current post object.
- * @param array    $args {
+ * @param array   $args {
  *     Array of arguments for building the post submit meta box.
  *
  *     @type string   $id       Meta box 'id' attribute.
@@ -1185,7 +1185,7 @@ function link_target_meta_box( $link ) {
  *
  * @param string $class
  * @param string $value
- * @param mixed $deprecated Never used.
+ * @param mixed  $deprecated Never used.
  */
 function xfn_check( $class, $value = '', $deprecated = '' ) {
 	global $link;

src/wp-admin/includes/misc.php

@@ -1190,7 +1190,7 @@ function wp_refresh_post_nonces( $response, $data, $screen_id ) {
  *
  * @since 5.0.0
  *
- * @param array  $response  The Heartbeat response.
+ * @param array $response The Heartbeat response.
  * @return array The Heartbeat response.
  */
 function wp_refresh_heartbeat_nonces( $response ) {

src/wp-admin/includes/plugin.php

@@ -858,7 +858,7 @@ function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) {
  * @param string          $redirect     Redirect to page after successful activation.
  * @param bool            $network_wide Whether to enable the plugin for all sites in the network.
  *                                      Default false.
- * @param bool $silent                  Prevent calling activation hooks. Default false.
+ * @param bool            $silent       Prevent calling activation hooks. Default false.
  * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation.
  */
 function activate_plugins( $plugins, $redirect = '', $network_wide = false, $silent = false ) {

src/wp-admin/includes/post.php

@@ -13,7 +13,7 @@
  *
  * @since 2.6.0
  *
- * @param bool $update Are we updating a pre-existing post?
+ * @param bool  $update    Are we updating a pre-existing post?
  * @param array $post_data Array of post data. Defaults to the contents of $_POST.
  * @return array|WP_Error Array of post data on success, WP_Error on failure.
  */
@@ -1505,13 +1505,13 @@ function get_sample_permalink_html( $id, $new_title = null, $new_slug = null ) {
 }
 
 /**
- * Output HTML for the post thumbnail meta-box.
+ * Returns HTML for the post thumbnail meta box.
  *
  * @since 2.9.0
  *
- * @param int $thumbnail_id ID of the attachment used for thumbnail
+ * @param int         $thumbnail_id ID of the attachment used for thumbnail
- * @param int|WP_Post $post Optional. The post ID or object associated with the thumbnail, defaults to global $post.
+ * @param int|WP_Post $post         Optional. The post ID or object associated with the thumbnail, defaults to global $post.
- * @return string html
+ * @return string The post thumbnail HTML.
  */
 function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
 	$_wp_additional_image_sizes = wp_get_additional_image_sizes();

src/wp-admin/includes/privacy-tools.php

@@ -218,7 +218,7 @@ function _wp_personal_data_cleanup_requests() {
  * @since 4.9.6
  * @since 5.4.0 Added the `$group_id` and `$groups_count` parameters.
  *
- * @param array $group_data {
+ * @param array  $group_data {
  *     The group data to render.
  *
  *     @type string $group_label  The user-facing heading for the group, e.g. 'Comments'.

src/wp-admin/includes/screen.php

@@ -197,7 +197,7 @@ function get_hidden_meta_boxes( $screen ) {
  * @since 3.1.0
  *
  * @param string $option An option name.
- * @param mixed $args Option-dependent arguments.
+ * @param mixed  $args   Option-dependent arguments.
  */
 function add_screen_option( $option, $args = array() ) {
 	$current_screen = get_current_screen();

src/wp-admin/includes/template.php

@@ -1795,8 +1795,8 @@ function add_settings_error( $setting, $code, $message, $type = 'error' ) {
  *
  * @global array $wp_settings_errors Storage array of errors registered during this pageload
  *
- * @param string $setting Optional slug title of a specific setting whose errors you want.
+ * @param string $setting  Optional. Slug title of a specific setting whose errors you want.
- * @param boolean $sanitize Whether to re-sanitize the setting value before returning errors.
+ * @param bool   $sanitize Optional. Whether to re-sanitize the setting value before returning errors.
  * @return array Array of settings errors.
  */
 function get_settings_errors( $setting = '', $sanitize = false ) {

src/wp-admin/users.php

@@ -247,8 +247,8 @@ switch ( $wp_list_table->current_action() ) {
 		 *
 		 * @since 5.2.0
 		 *
-		 * @param boolean $users_have_additional_content Whether the users have additional content. Default false.
+		 * @param bool  $users_have_additional_content Whether the users have additional content. Default false.
-		 * @param int[]   $userids                       Array of IDs for users being deleted.
+		 * @param int[] $userids                       Array of IDs for users being deleted.
 		 */
 		$users_have_content = (bool) apply_filters( 'users_have_additional_content', false, $userids );
 

src/wp-comments-post.php

@@ -50,7 +50,7 @@ $cookies_consent = ( isset( $_POST['wp-comment-cookies-consent'] ) );
  *
  * @param WP_Comment $comment         Comment object.
  * @param WP_User    $user            Comment author's user object. The user may not exist.
- * @param boolean    $cookies_consent Comment author's consent to store cookies.
+ * @param bool       $cookies_consent Comment author's consent to store cookies.
  */
 do_action( 'set_comment_cookies', $comment, $user, $cookies_consent );
 

src/wp-includes/category-template.php

@@ -1082,6 +1082,9 @@ function walk_category_tree( ...$args ) {
 	if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
 		$walker = new Walker_Category;
 	} else {
+		/**
+		 * @var Walker $walker
+		 */
 		$walker = $args[2]['walker'];
 	}
 	return $walker->walk( ...$args );
@@ -1105,6 +1108,9 @@ function walk_category_dropdown_tree( ...$args ) {
 	if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
 		$walker = new Walker_CategoryDropdown;
 	} else {
+		/**
+		 * @var Walker $walker
+		 */
 		$walker = $args[2]['walker'];
 	}
 	return $walker->walk( ...$args );

src/wp-includes/class-wp-embed.php

@@ -101,10 +101,12 @@ class WP_Embed {
 	 *
 	 * This function should probably also only be used for sites that do not support oEmbed.
 	 *
-	 * @param string $id An internal ID/name for the handler. Needs to be unique.
+	 * @param string   $id       An internal ID/name for the handler. Needs to be unique.
-	 * @param string $regex The regex that will be used to see if this handler should be used for a URL.
+	 * @param string   $regex    The regex that will be used to see if this handler should be used for a URL.
 	 * @param callable $callback The callback function that will be called if the regex is matched.
-	 * @param int $priority Optional. Used to specify the order in which the registered handlers will be tested (default: 10). Lower numbers correspond with earlier testing, and handlers with the same priority are tested in the order in which they were added to the action.
+	 * @param int      $priority Optional. Used to specify the order in which the registered handlers will be tested.
+	 *                           Lower numbers correspond with earlier testing, and handlers with the same priority are
+	 *                           tested in the order in which they were added to the action. Default 10.
 	 */
 	public function register_handler( $id, $regex, $callback, $priority = 10 ) {
 		$this->handlers[ $priority ][ $id ] = array(

src/wp-includes/class-wp-image-editor-imagick.php

@@ -509,12 +509,12 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor {
 	 *
 	 * @since 3.5.0
 	 *
-	 * @param int  $src_x The start x position to crop from.
+	 * @param int  $src_x   The start x position to crop from.
-	 * @param int  $src_y The start y position to crop from.
+	 * @param int  $src_y   The start y position to crop from.
-	 * @param int  $src_w The width to crop.
+	 * @param int  $src_w   The width to crop.
-	 * @param int  $src_h The height to crop.
+	 * @param int  $src_h   The height to crop.
-	 * @param int  $dst_w Optional. The destination width.
+	 * @param int  $dst_w   Optional. The destination width.
-	 * @param int  $dst_h Optional. The destination height.
+	 * @param int  $dst_h   Optional. The destination height.
 	 * @param bool $src_abs Optional. If the source crop points are absolute.
 	 * @return bool|WP_Error
 	 */

src/wp-includes/class-wp-image-editor.php

@@ -122,12 +122,12 @@ abstract class WP_Image_Editor {
 	 * @since 3.5.0
 	 * @abstract
 	 *
-	 * @param int $src_x The start x position to crop from.
+	 * @param int  $src_x   The start x position to crop from.
-	 * @param int $src_y The start y position to crop from.
+	 * @param int  $src_y   The start y position to crop from.
-	 * @param int $src_w The width to crop.
+	 * @param int  $src_w   The width to crop.
-	 * @param int $src_h The height to crop.
+	 * @param int  $src_h   The height to crop.
-	 * @param int $dst_w Optional. The destination width.
+	 * @param int  $dst_w   Optional. The destination width.
-	 * @param int $dst_h Optional. The destination height.
+	 * @param int  $dst_h   Optional. The destination height.
 	 * @param bool $src_abs Optional. If the source crop points are absolute.
 	 * @return bool|WP_Error
 	 */
@@ -231,7 +231,7 @@ abstract class WP_Image_Editor {
 			 * Applies only during initial editor instantiation, or when set_quality() is run
 			 * manually without the `$quality` argument.
 			 *
-			 * set_quality() has priority over the filter.
+			 * The WP_Image_Editor::set_quality() method has priority over the filter.
 			 *
 			 * @since 3.5.0
 			 *
@@ -247,7 +247,7 @@ abstract class WP_Image_Editor {
 				 * Applies only during initial editor instantiation, or when set_quality() is run
 				 * manually without the `$quality` argument.
 				 *
-				 * set_quality() has priority over the filter.
+				 * The WP_Image_Editor::set_quality() method has priority over the filter.
 				 *
 				 * The filter is evaluated under two contexts: 'image_resize', and 'edit_image',
 				 * (when a JPEG image is saved to file).

src/wp-includes/class-wp-role.php

@@ -25,21 +25,22 @@ class WP_Role {
 	 * List of capabilities the role contains.
 	 *
 	 * @since 2.0.0
-	 * @var array
+	 * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
+	 *             represent whether the role has that capability.
 	 */
 	public $capabilities;
 
 	/**
 	 * Constructor - Set up object properties.
 	 *
-	 * The list of capabilities, must have the key as the name of the capability
+	 * The list of capabilities must have the key as the name of the capability
 	 * and the value a boolean of whether it is granted to the role.
 	 *
 	 * @since 2.0.0
 	 *
 	 * @param string $role         Role name.
-	 * @param bool[] $capabilities List of capabilities keyed by the capability name,
+	 * @param bool[] $capabilities Array of key/value pairs where keys represent a capability name and boolean values
-	 *                             e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
+	 *                             represent whether the role has that capability.
 	 */
 	public function __construct( $role, $capabilities ) {
 		$this->name         = $role;
@@ -51,8 +52,8 @@ class WP_Role {
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param string $cap Capability name.
+	 * @param string $cap   Capability name.
-	 * @param bool $grant Whether role has capability privilege.
+	 * @param bool   $grant Whether role has capability privilege.
 	 */
 	public function add_cap( $cap, $grant = true ) {
 		$this->capabilities[ $cap ] = $grant;
@@ -62,11 +63,6 @@ class WP_Role {
 	/**
 	 * Removes a capability from a role.
 	 *
-	 * This is a container for WP_Roles::remove_cap() to remove the
-	 * capability from the role. That is to say, that WP_Roles::remove_cap()
-	 * implements the functionality, but it also makes sense to use this class,
-	 * because you don't need to enter the role name.
-	 *
 	 * @since 2.0.0
 	 *
 	 * @param string $cap Capability name.
@@ -79,15 +75,10 @@ class WP_Role {
 	/**
 	 * Determines whether the role has the given capability.
 	 *
-	 * The capabilities is passed through the {@see 'role_has_cap'} filter.
-	 * The first parameter for the hook is the list of capabilities the class
-	 * has assigned. The second parameter is the capability name to look for.
-	 * The third and final parameter for the hook is the role name.
-	 *
 	 * @since 2.0.0
 	 *
 	 * @param string $cap Capability name.
-	 * @return bool True if the role has the given capability. False otherwise.
+	 * @return bool Whether the role has the given capability.
 	 */
 	public function has_cap( $cap ) {
 		/**
@@ -95,7 +86,8 @@ class WP_Role {
 		 *
 		 * @since 2.0.0
 		 *
-		 * @param bool[] $capabilities Associative array of capabilities for the role.
+		 * @param bool[] $capabilities Array of key/value pairs where keys represent a capability name and boolean values
+		 *                             represent whether the role has that capability.
 		 * @param string $cap          Capability name.
 		 * @param string $name         Role name.
 		 */

src/wp-includes/class-wp-user.php

@@ -53,10 +53,11 @@ class WP_User {
 	public $ID = 0;
 
 	/**
-	 * The individual capabilities the user has been given.
+	 * Capabilities that the individual user has been granted outside of those inherited from their role.
 	 *
 	 * @since 2.0.0
-	 * @var array
+	 * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
+	 *             represent whether the user has that capability.
 	 */
 	public $caps = array();
 
@@ -72,7 +73,7 @@ class WP_User {
 	 * The roles the user is part of.
 	 *
 	 * @since 2.0.0
-	 * @var array
+	 * @var string[]
 	 */
 	public $roles = array();
 

src/wp-includes/comment.php

@@ -560,7 +560,7 @@ function wp_queue_comments_for_comment_meta_lazyload( $comments ) {
  *
  * @param WP_Comment $comment         Comment object.
  * @param WP_User    $user            Comment author's user object. The user may not exist.
- * @param boolean    $cookies_consent Optional. Comment author's consent to store cookies. Default true.
+ * @param bool       $cookies_consent Optional. Comment author's consent to store cookies. Default true.
  */
 function wp_set_comment_cookies( $comment, $user, $cookies_consent = true ) {
 	// If the user already exists, or the user opted out of cookies, don't set cookies.

src/wp-includes/embed.php

@@ -132,10 +132,10 @@ function _wp_oembed_get_object() {
  *
  * @see WP_oEmbed
  *
- * @param string  $format   The format of URL that this provider can handle. You can use asterisks
+ * @param string $format   The format of URL that this provider can handle. You can use asterisks
- *                          as wildcards.
+ *                         as wildcards.
- * @param string  $provider The URL to the oEmbed provider.
+ * @param string $provider The URL to the oEmbed provider.
- * @param boolean $regex    Optional. Whether the `$format` parameter is in a RegEx format. Default false.
+ * @param bool   $regex    Optional. Whether the `$format` parameter is in a RegEx format. Default false.
  */
 function wp_oembed_add_provider( $format, $provider, $regex = false ) {
 	if ( did_action( 'plugins_loaded' ) ) {

src/wp-includes/post-template.php

@@ -1522,6 +1522,9 @@ function walk_page_tree( $pages, $depth, $current_page, $r ) {
 	if ( empty( $r['walker'] ) ) {
 		$walker = new Walker_Page;
 	} else {
+		/**
+		 * @var Walker $walker
+		 */
 		$walker = $r['walker'];
 	}
 
@@ -1551,6 +1554,9 @@ function walk_page_dropdown_tree( ...$args ) {
 	if ( empty( $args[2]['walker'] ) ) { // The user's options are the third parameter.
 		$walker = new Walker_PageDropdown;
 	} else {
+		/**
+		 * @var Walker $walker
+		 */
 		$walker = $args[2]['walker'];
 	}
 

src/wp-includes/sitemaps.php

@@ -61,7 +61,7 @@ function wp_get_sitemap_providers() {
  *
  * @param string               $name     Unique name for the sitemap provider.
  * @param WP_Sitemaps_Provider $provider The `Sitemaps_Provider` instance implementing the sitemap.
- * @return bool Returns true if the sitemap was added. False on failure.
+ * @return bool Whether the sitemap was added.
  */
 function wp_register_sitemap_provider( $name, WP_Sitemaps_Provider $provider ) {
 	$sitemaps = wp_sitemaps_get_server();

src/wp-includes/sitemaps/class-wp-sitemaps.php

@@ -224,7 +224,7 @@ class WP_Sitemaps {
 	 * @since 5.5.0
 	 *
 	 * @param bool     $bypass Pass-through of the pre_handle_404 filter value.
-	 * @param WP_Query $query The WP_Query object.
+	 * @param WP_Query $query  The WP_Query object.
 	 * @return bool Bypass value.
 	 */
 	public function redirect_sitemapxml( $bypass, $query ) {
@@ -250,7 +250,7 @@ class WP_Sitemaps {
 	 * @since 5.5.0
 	 *
 	 * @param string $output robots.txt output.
-	 * @param bool   $public Whether the site is public or not.
+	 * @param bool   $public Whether the site is public.
 	 * @return string The robots.txt output.
 	 */
 	public function add_robots( $output, $public ) {

src/wp-includes/widgets/class-wp-nav-menu-widget.php

@@ -95,15 +95,15 @@ class WP_Nav_Menu_Widget extends WP_Widget {
 		 * @since 4.2.0
 		 * @since 4.4.0 Added the `$instance` parameter.
 		 *
-		 * @param array    $nav_menu_args {
+		 * @param array   $nav_menu_args {
 		 *     An array of arguments passed to wp_nav_menu() to retrieve a navigation menu.
 		 *
 		 *     @type callable|bool $fallback_cb Callback to fire if the menu doesn't exist. Default empty.
 		 *     @type mixed         $menu        Menu ID, slug, or name.
 		 * }
-		 * @param WP_Term  $nav_menu      Nav menu object for the current menu.
+		 * @param WP_Term $nav_menu      Nav menu object for the current menu.
-		 * @param array    $args          Display arguments for the current widget.
+		 * @param array   $args          Display arguments for the current widget.
-		 * @param array    $instance      Array of settings for the current widget.
+		 * @param array   $instance      Array of settings for the current widget.
 		 */
 		wp_nav_menu( apply_filters( 'widget_nav_menu_args', $nav_menu_args, $nav_menu, $args, $instance ) );