docs: rust: explain that `///` vs. `//` applies to private items too
Subsystems (2)
Miguel Ojeda
maintainerPATCH 1/1 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 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.
--- Documentation/rust/coding-guidelines.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+)
Documentation/rust/coding-guidelines.rst +12 -0
@@ -85,6 +85,18 @@ written after the documentation, e.g.: // ... } +This applies to both public and private items. This increases consistency with +public items, allows changes to visibility with less changes involved and will +allow us to potentially generate the documentation for private items as well. +In other words, if documentation is written for a private item, then ``///`` +should still be used. For instance: + +.. code-block:: rust + + /// My private function. + // TODO: ... + fn f() {} + One special kind of comments are the ``// SAFETY:`` comments. These must appear before every ``unsafe`` block, and they explain why the code inside the block is correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
base-commit: c1b4071ec3a6a594df6c49bf8f04a60a88072525
Signature · 1 line
2.49.0
Quoted 16 lines · Miguel Ojeda
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,
rustdoclints as usual for those, too, so we may want to do it even if we do not use the result.
Quoted 6 lines
Thus document this explicitly.
Quoted 16 lines · Miguel Ojeda
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,
rustdoclints as usual for those, too, so we may want to do it even if we do not use the result.
Quoted 7 lines
Thus document this explicitly.
Cc Viresh Kumar <[email protected]>Link https://lore.kernel.org/rust-for-linux/CANiq72n_C7exSOMe5yf-7jKKnhSCv+a9QcD=OE2B_Q2UFBL3Xg@mail.gmail.com/ open hereSigned-off-by Miguel Ojeda <[email protected]>---
Quoted 9 lines · Miguel Ojeda
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.
changes ?
Quoted 7 lines
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,
rustdoclints as usual for those, too, so we may want to do it even if we do not use the result.Thus document this explicitly.
Signature · 1 line
viresh
Miguel Ojeda
AppliedQuoted 17 lines · Miguel Ojeda
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,
rustdoclints as usual for those, too, so we may want to do it even if we do not use the result.
Quoted 6 lines
Thus document this explicitly.
Applied to rust-next -- thanks everyone!
[ Fixed typo. - Miguel ]
Cheers,
Miguel