The distinction I'm trying to make is between the necessary documentation to even have an API contract vs. "reminding" people of things that are defined elsewhere.
To have an API contract we of course need to write something. Like this produces a [lazy](link) [adapter](link). Spending several sentences on explaining what being lazy implies and corollaries thereof and warnings... is not documenting what the method does, it's rehashing context.
It's a really basic property of how people think.
I have made that mistake myself, even on unsafe code. I even made a bit of noise about it. But in the end I realized that it was on me. The contract matters, it's there for a reason, it's unsafe for a reason and cutting corners with learning the context won't work. And this isn't specific to unsafe code, lots of things have correctness contracts or absence-of-a-guarantee negative space.
But we also know that copy-pasting a bunch of stuff everywhere makes things worse because it gets more confusing by becoming inconsistent over time, and interrupting people who want to know about the specific method, not general things that are always true.
It feels like there's a potential rustdoc feature to help here to make this kind of maintenance easier.
Whether that is being able to define something that can be referenced or inlined from a module doc comment into a per-item one, like:
//! Composable external iteration.
//!
//! ...
//!
//! [^lazy]: Iterator functions are lazy, see [laziness](#laziness) for more information.
/// some_fn does something.
///
/// [^lazy]
pub fn some_fn() {}
Or perhaps some way of actually just saying add this to all items as a suffix:
//! Composable external iteration.
//!
//! ...
//!
//! [copy_to_all_fns]: This function is lazy.
/// some_fn does something.
pub fn some_fn() {}
We use function calls and similar all the time in code - given documentation for a particular item is typically read in isolation, having convenient ways to either inline copies while deduplicate the source, or insert references to elsewhere, seems useful?
you can actually just use macros for this, everything inside #[doc = …] is eagerly expanded. this includes include_str!, but also things like stringify! and concat!.
hopefully macros 2.0 will make trivial macros like that a bit more convenient to write.