Add usage examples

[newpavlov]

It would be nice to refer to the trait crates for advanced examples from implementation crates.

[tarcieri]

The tricky part is the trait crates don't have concrete implementations, so it requires making a "fake" implementation and writing the usage docs in terms of that (at least if you want doctests).

I think it'd be nice if the trait crates provided the bulk of usage-related documentation/information, but I think it's still nice if the individual crates have quick, concrete usage examples that work out-of-the-box.

[newpavlov]

The tricky part is the trait crates don't have concrete implementations, so it requires making a "fake" implementation and writing the usage docs in terms of that (at least if you want doctests).

I also thought that it would create a circular dependency, but you can add a dev-dependency which depends on a current crate and use it in tests. IIUC it works because tests get compiled separately from the library crate.

I think it's still nice if the individual crates have quick, concrete usage examples that work out-of-the-box

Yes, I also think that it's nice to have small usage examples in implementation crates, which also act like a test.