Merge #376: Add examples to key module

aa828f0 Improve documentation in the key module (Tobin Harding)
9e46d6f Add examples to types and methods in key module (Tobin Harding)
a7f3d9b Improve key module docs (Tobin Harding)
6d23614 Improve lib.rs rustdocs (Tobin Harding)
4c4268f Improve docs on method generate_keypair (Tobin Harding)

Pull request description:

  This PR is an initial attempt to more thoroughly test our public API.

  Add examples to various types/methods/functions in the key module.

  I'm not entirely sure when is enough, do we want an example on every single public method, function, and type or is this overkill. In this PR I tried to find a balance by doing ever method/function that took an argument that is a custom type from this lib. I think this should be extended to include return values too though ...

  Thanks to @thomaseizinger for the idea!

  First 2 patches are docs improvements to `lib.rs`.

ACKs for top commit:
  apoelstra:
    ACK aa828f0

Tree-SHA512: 9383ad263469f98ce7e988d47edc1482a09a0ce82f43d3991bd80aabdf621430f4a3c86be4debf33232dcb1d60d3e81f2c6d930ea7de7aa0e34b037accd7bc98