Use macros for boilerplate documentation?

[tarcieri]

Several crates have copy-and-paste boilerplate documentation which ultimately shows how to use a trait-based API, but giving concrete examples for a particular algorithm.

It seems like we could potentially use macros to write #![doc] or #[doc] depending on context, and potentially accepting a type name to customize a specific example. After that it can use concat! to assemble the documentation, which should even make it possible to emit full code examples, but customized to algorithm-specific type names.

[tarcieri]

Started experimenting with doing this for the aead crate in #1945

[newpavlov]

Sounds good to me, but are you sure that we don't want the examples to be part of crates README?

[tarcieri]

This approach wouldn’t work with README.md files

[newpavlov]

Yes, this is why I am asking whether you are sure that we do not want the examples to be part of README. It's one of the first places users read, so it may worth the cost of some copy-paste boilerplate.

[tarcieri]

I put the usage docs where they are already because I like for the README.md to be a high-level overview and for the detailed usage docs to be in the rustdoc.

It's ~90 lines of documentation, each one customized to a particular cipher.

I think the macro-based approach will help us produce much better documentation which can be updated in one place for all ciphers, and the choice of whether the usage examples go in the README.md or the rustdoc is six-of-one, half-dozen-of-another so long as they do wind up in the rustdoc.