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.

[newpavlov]

A potential alternative could be to add extended docs and examples to the aead crate (e.g. to a separate cookbook/tutorial module) or to the book and link them from the implementation crates. We have a similar thing in the hash crates in the form of linking the repo readme. It also would allow us to remove some of the features from the AEAD crates (e.g. I am not sure it's worth to have feature forwarding for arrayvec/bytes/heapleass).

[tarcieri]

I think we've received a lot of complaints about people having trouble trying to find the documentation when they have to click through to the trait crate, and then the documentation isn't personalized to the crate/algorithm they're looking at.

[newpavlov]

We do not have links to a text equivalent to the hashes README, so it's not surprising that people find the current aead docs a bad starting point. I think it could be sufficient to have a short basic example (probably Vec-based) in crate docs and explain more advanced APIs (detached, inout, heapless, etc.) in a linked external text.

[tarcieri]

I was making a general comment on the overall state of the documentation across the project. I can’t say I’ve specifically heard people complain about aead.

One comment I’ve seen over and over about the documentation in the project is people get confused when they need to “click through” to a different crate to find the documentation they need. It harms discoverability of the documentation, and as I said earlier, the documentation isn’t for the crate they’re actually trying to use.

My solution for that for the AEADs was this boilerplate documentation which is personalized to each crate, which is a model I think we can and should expand on.