Re: [PATCH V10 14/15] rust: opp: Extend OPP abstractions with cpufreq support

[Miguel Ojeda]

On Wed, Apr 16, 2025 at 12:40 PM Viresh Kumar <viresh.kumar@xxxxxxxxxx> wrote:
>
> Hmm, I did not use /// as the comments were added to private
> definitions.
>
> Sorry for the dumb question, but why should we use /// in such cases ?
> They will never show up in documentation anyway, right ?

It is not a dumb question at all!

The reason is that using `///` is not just for `rustdoc`, but intended
to convey it is documentation for the item, rather than a comment that
talks about implementation details or things like TODOs.

So you may have both `///` or `//` even for private items, and it is a
meaningful difference for the reader. Plus it makes it consistent with
the public ones.

Moreover, if we ever move to documenting private items, then we will
want these to be correct -- `rustdoc` supports generating docs with
private items (e.g. it puts a cute lock emoji on private items in the
lists etc.). I think some kernel developers would appreciate it -- we
could offer both versions in rust.docs.kernel.org with a toggle, for
instance.

Cheers,
Miguel