More examples in `rustdoc` documentation

[dpc]

I'm sorry this is not a PR implementing it, but I'd like to point out that documentation could really use more rustdoc examples. Looking at an examples on docs.rs/<crate> is the fasted thing to look up usage and functionality of a crate.

[matklad]

Alternatively, there could be a link to https://boats.gitlab.io/failure/ from the crate docs. If one discovers failure via docs.rs, one might wrongly think that it is not thoroughly documented:

https://gitter.im/rust-lang/rust?at=5a325ef1540c78242dc32fa6

[dpc]

IMO, it would be much better if all documentation would be a part of the source code and documentation autogenerated on https://docs.rs . Linking is better than nothing, but still.