Docs: Further improve documentation of known return types, plus other docs fixes.

See #48303


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

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

@@ -864,7 +864,8 @@ class WP_User {
 	 *
 	 * @since 4.9.0
 	 *
-	 * @return array User capabilities array.
+	 * @return bool[] List of capabilities keyed by the capability name,
+	 *                e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
 	 */
 	private function get_caps_data() {
 		$caps = get_user_meta( $this->ID, $this->cap_key, true );