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.

[tarcieri]

I'll note a big disadvantage of trying to put all documentation in README.md as opposed to splitting out e.g. usage details into standard rustdoc is you can't use intra-doc links, or at best they won't render right on GitHub.

I think having a README.md with a code example and high-level overview is great, but it's unsatisfactory for getting into the details.

[newpavlov]

For intra-doc links we can use the following trick:

This is an [`Item`] link in README.

[`Item`]: https://docs.rs/crate/item.html

lib.rs:

// Re-define intra-crate links
//! [`Item`]: Item

#![doc = include_str!("../README.md")]

Granted, it's a bit annoying to maintain, but it can work fine if we do not have too many such intra-crate links.

I agree that we should not have huge readmes which cover various usage details. But I think that instead of duplicating those details in each crate, it's better to describe them in one place, either in the parent repository's README like we did in the hashes repo, or, even better, in the book.

[tarcieri]

I strongly disagree. People get confused by not having documentation that's directly relevant and applicable to their crates, with copy-paste examples that Just Work.

Trying to put all of the documentation into the trait crates makes is hard to discover, means it isn't directly relevant to the crate they're trying to use, and is something people have complained to me about over and over and over and over. I am very sick of hearing about it.

[newpavlov]

Cluttering the root crate docs with multi-page examples is also not great in my opinion. As a middle ground between the book and examples in README we could use doc modules, i.e. modules which do not contain any code and used only for additional docs.