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-screen.php

@@ -496,7 +496,7 @@ final class WP_Screen {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param string $option Option ID
+	 * @param string $option Option ID.
 	 * @param mixed  $args   Option-dependent arguments.
 	 */
 	public function add_option( $option, $args = array() ) {

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/post.php

@@ -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|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/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,7 +247,7 @@ 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.
 		 */
 		$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

@@ -104,7 +104,9 @@ class WP_Embed {
 	 * @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 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.php

@@ -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;
@@ -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

@@ -135,7 +135,7 @@ function _wp_oembed_get_object() {
  * @param string $format   The format of URL that this provider can handle. You can use asterisks
  *                         as wildcards.
  * @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

@@ -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 ) {