crypto/keys: improve documentation

[alessio]

Replace out of date crypto/keys README.md file
with crypto/keys package documentation.

Populate client keys commands help screen with
more information regarding keyring backends.

Forked from: #5822

---

For contributor use:

• Targeted PR against correct branch (see CONTRIBUTING.md)
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the module structure standards.
• Wrote unit and integration tests
• Updated relevant documentation (docs/) or specification (x/<module>/spec/)
• Added relevant godoc comments.
• Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
• Re-reviewed Files changed in the Github PR explorer

---

For admin use:

• Added appropriate labels to PR (ex. WIP, R4R, docs, etc)
• Reviewers assigned
• Squashed all commits, uses message "Merge pull request #XYZ: [title]" (coding standards)

[golangcibot]

package comment should not have leading space (from golint)

[alexanderbez]

Have you viewed the rendered godoc locally for this? This shouldn't be indented like this.

[alessio]

it's the same as https://golang.org/src/fmt/doc.go

[codecov]

Codecov Report

Merging #5833 into master will increase coverage by 0.02%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #5833      +/-   ##
==========================================
+ Coverage    32.3%   32.33%   +0.02%     
==========================================
  Files         353      353              
  Lines       39461    39475      +14     
==========================================
+ Hits        12749    12763      +14     
  Misses      25439    25439              
  Partials     1273     1273

Impacted Files	Coverage Δ
crypto/keys/keyring.go	51.91% <ø> (ø)	⬆️
client/keys/root.go	100% <100%> (ø)	⬆️

[alexanderbez]

Minor formatting nits, other LGTM.

[alexanderbez]

Have you viewed the rendered godoc locally for this? This shouldn't be indented like this.

[alexanderbez]

Formatting seems off here.

[alessio]

Tested with go doc

[alexanderbez]

Right, but it seems off. The os doesn't line up with the other entries.

[alessio]

Oh I see why. I used tabs for formatting (same as https://golang.org/src/fmt/doc.go). Rendered result seems correctly aligned though (see below)

[alessio]

This is how go doc renders the doc @alexanderbez - I'll test it with -html too shortly:

alessio@bangalter:~/work/cosmos-sdk$ go doc ./crypto/keys/
package keys // import "github.com/cosmos/cosmos-sdk/crypto/keys"

Package keys provides common key management API.


The Keybase interface

The Keybase interface defines the methods that a type needs to implement to
be used as key storage backend. This package provides few implementations
out-of-the-box.


New

The New constructor returns an on-disk implementation backed by LevelDB
storage that has been the default implementation used by the SDK until
v0.38.0. Due to security concerns, it is recommended to drop it in favor of
the NewKeyring or NewKeyringFile constructors as it will be removed in
future releases.


NewInMemory

The NewInMemory constructor returns an implementation backed by an
in-memory, goroutine-safe map that has historically been used for testing
purposes or on-the-fly key generation as the generated keys are discarded
when the process terminates or the type instance is garbage collected.


NewKeyring

The NewKeyring constructor returns an implementation backed by a keyring
library (https://github.com/99designs/keyring), whose aim is to provide a
common abstraction and uniform interface between secret stores available for
Windows, macOS, and most GNU/Linux distributions as well as operating
system-agnostic encrypted file-based backends.

The backends:

    os		The instance returned by this constructor uses the operating system's default
    		credentials store to handle keys storage operations securely. It should be noted
    		that the keyring keyring may be kept unlocked for the whole duration of the user
    		session.
    file	This backend more closely resembles the previous keyring storage used prior to
    		v0.38.1. It stores the keyring encrypted within the apps configuration directory.
    		This keyring will request a password each time it is accessed, which may occur
    		multiple times in a single command resulting in repeated password prompts.
    kwallet	This backend uses KDE Wallet Manager as a credentials management application:
    		https://github.com/KDE/kwallet
    pass	This backend uses the pass command line utility to store and retrieve keys:
    		https://www.passwordstore.org/
    test	This backend stores keys insecurely to disk. It does not prompt for a password to
    		be unlocked and it should be use only for testing purposes.

[alexanderbez]

ACK -- pending CI lint fix 🍊