Re: [PATCH 2/3] rust: net: phy: make example buildable

[Miguel Ojeda]

On Tue, Nov 11, 2025 at 12:34 AM FUJITA Tomonori
<fujita.tomonori@xxxxxxxxx> wrote:
>
> I think that some code begin lines with # for use lines in a "#
> Examples" section, while others do not. Which style is recommended?

There is no hard rule for all cases -- we typically hide things that
are not important for the example (e.g. fake `mod bindings` that are
used to support the example but aren't important and would bloat the
example or confuse the reader).

For imports, some people prefer to see them, others don't. Here, for
instance, it may be interesting to show the paths (e.g. that the
`Device` is a `net::phy::` one, or where `C22` is coming from), so we
could unhide it. So up to you!

So I think the rule is really: if it is something that we think people
should see to actually understand the example, then we should show it.

And if it is something that would confuse them more than help, or that
generally should not be used in real code (like the fake bindings),
then we should hide it.

Ideally `rustdoc` could perhaps support showing the hidden parts with
the click of a button or similar -- there was e.g.:

    https://github.com/rust-lang/rust/pull/86892

On the other hand, there is already a "Source" button nearby that one
can click to see it, so it is not too bad. But, yeah, if they need to
do that, it is likely it shouldn't have been hidden to begin with.

Cheers,
Miguel