diff -r 3d4e9c994f10 -r a86126ab1dd4 wp/wp-includes/class-wp-role.php
--- a/wp/wp-includes/class-wp-role.php	Tue Oct 22 16:11:46 2019 +0200
+++ b/wp/wp-includes/class-wp-role.php	Tue Dec 15 13:49:49 2020 +0100
@@ -25,20 +25,22 @@
 	 * 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 array $capabilities List of capabilities.
+	 * @param string $role         Role name.
+	 * @param bool[] $capabilities Array of key/value pairs where keys represent a capability name and boolean values
+	 *                             represent whether the role has that capability.
 	 */
 	public function __construct( $role, $capabilities ) {
 		$this->name         = $role;
@@ -50,8 +52,8 @@
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param string $cap Capability name.
-	 * @param bool $grant Whether role has capability privilege.
+	 * @param string $cap   Capability name.
+	 * @param bool   $grant Whether role has capability privilege.
 	 */
 	public function add_cap( $cap, $grant = true ) {
 		$this->capabilities[ $cap ] = $grant;
@@ -61,11 +63,6 @@
 	/**
 	 * 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.
@@ -78,15 +75,10 @@
 	/**
 	 * 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 ) {
 		/**
@@ -94,7 +86,8 @@
 		 *
 		 * @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.
 		 */