On Wed, Apr 16, 2025 at 1:25 PM Miguel Ojeda <ojeda@xxxxxxxxxx> wrote: > > Sometimes kernel developers use `//` for documenting private items, > since those do not get rendered at the moment. > > That is reasonable, but the intention behind `///` (and `//!`) vs. `//` > is to convey the distinction between documentation and other kinds of > comments, such as implementation details or TODOs. > > It also increases consistency with the public items and thus e.g. allows > to change visibility of an item with less changed involved. > > It is not just useful for human readers, but also tooling. For instance, > we may want to eventually generate documentation for private items > (perhaps as a toggle in the HTML UI). On top of that, `rustdoc` lints > as usual for those, too, so we may want to do it even if we do not use > the result. > > Thus document this explicitly. > > Cc: Viresh Kumar <viresh.kumar@xxxxxxxxxx> > Link: https://lore.kernel.org/rust-for-linux/CANiq72n_C7exSOMe5yf-7jKKnhSCv+a9QcD=OE2B_Q2UFBL3Xg@xxxxxxxxxxxxxx/ > Link: https://github.com/Rust-for-Linux/linux/issues/1157 > Signed-off-by: Miguel Ojeda <ojeda@xxxxxxxxxx> Applied to `rust-next` -- thanks everyone! [ Fixed typo. - Miguel ] Cheers, Miguel
