Docs: Switch more docs over to typed array notation, plus some fixes.

See #48303, #41756


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

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

@@ -147,9 +147,10 @@ class WP_Roles {
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param string $role Role name.
+	 * @param string $role         Role name.
 	 * @param string $display_name Role display name.
-	 * @param array $capabilities List of role capabilities in the above format.
+	 * @param bool[] $capabilities List of capabilities keyed by the capability name,
+	 *                             e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
 	 * @return WP_Role|void WP_Role object, if role is added.
 	 */
 	public function add_role( $role, $display_name, $capabilities = array() ) {