tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: rust: explain that `///` vs. `//` applies to private items too

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 changes 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.

Link: https://lore.kernel.org/rust-for-linux/CANiq72n_C7exSOMe5yf-7jKKnhSCv+a9QcD=OE2B_Q2UFBL3Xg@mail.gmail.com/
Link: https://github.com/Rust-for-Linux/linux/issues/1157
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Reviewed-by: Viresh Kumar <viresh.kumar@linaro.org>
Link: https://lore.kernel.org/r/20250416112454.2503872-1-ojeda@kernel.org
[ Fixed typo. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Miguel Ojeda 79d04e73 878620c5

+12
+12
Documentation/rust/coding-guidelines.rst
··· 85 85 // ... 86 86 } 87 87 88 + This applies to both public and private items. This increases consistency with 89 + public items, allows changes to visibility with less changes involved and will 90 + allow us to potentially generate the documentation for private items as well. 91 + In other words, if documentation is written for a private item, then ``///`` 92 + should still be used. For instance: 93 + 94 + .. code-block:: rust 95 + 96 + /// My private function. 97 + // TODO: ... 98 + fn f() {} 99 + 88 100 One special kind of comments are the ``// SAFETY:`` comments. These must appear 89 101 before every ``unsafe`` block, and they explain why the code inside the block is 90 102 correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.: