Improve top-level command descriptions; add Handbook links

[hearvox]

Related: /wp-cli/issues/4302

Changes:

---

Improve 'wp cap' command description in:
https://github.com/wp-cli/role-command/blob/master/src/Capabilities_Command.php
Command: wp cap
Current description: Manage user capabilities.

New description:
Adds, removes, and lists capabilities of a user role.

See references for Roles and Capabilitiesand WP User class.

---

Improve command description in:
https://github.com/wp-cli/role-command/blob/master/src/Role_Command.php
Command: wp role
Current description: Manage user roles.

New description:
Manages user roles, including creating new roles and resetting to defaults.

See references for Roles and Capabilitiesand WP User class.

[miya0001]

Can you add a space before and?

[miya0001]

Can you add a space before and?

[hearvox]

Will do, then I'll close this PR and submit a new one, correct. Before I do I'll wait to see what folk say about the line-break.

Long and multiple sentences in the descriptions are a problem b/c forced line breaks look OK in the code, for example, of this existing description:
https://github.com/hearvox/shell-command/edit/master/src/Shell_Command.php

But are grammatically wrong, bad for a11y, and look funny in the Handbook:
https://developer.wordpress.org/cli/commands/shell/

[miya0001]

wp role:

wp cap:

[miya0001]

I feel uncomfortable at the position of the line break at description.
But I can understand it is difficult to solve.

@wp-cli/committers Any thoughts?

[schlessera]

Authoring props: @hearvox & @ako80218

[schlessera]

@miya0001 We'll deal with the word-wrapping through the parsing code.