Merge rust-bitcoin/rust-secp256k1#376: Add examples to key module

aa828f01a5727f0b056975cdbcaedbb24efb78bd Improve documentation in the key module (Tobin Harding)
9e46d6f1220c66b095fa061017bf2596e270328f Add examples to types and methods in key module (Tobin Harding)
a7f3d9bcfde1719966adf2d8abc3b2a6dd98d591 Improve key module docs (Tobin Harding)
6d23614467e8f51ce7a1b4defdd777f5320f6c4c Improve lib.rs rustdocs (Tobin Harding)
4c4268f1adde945acf1eb247ad8b2a235134749c 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 aa828f01a5727f0b056975cdbcaedbb24efb78bd

Tree-SHA512: 9383ad263469f98ce7e988d47edc1482a09a0ce82f43d3991bd80aabdf621430f4a3c86be4debf33232dcb1d60d3e81f2c6d930ea7de7aa0e34b037accd7bc98

Author: chain-forgexcr45