[PATCH 1/3] rust: net: phy: fix example's references to `C{22,45}`

[PATCH 1/3] rust: net: phy: fix example's references to `C{22,45}`

[Miguel Ojeda]

The example refers to `phy::C{22,45}`, but there are no such items --
they are within `reg`.

Thus fix it.

Fixes: 5114e05a3cfa ("rust: net::phy unified genphy_read_status function for C22 and C45 registers")
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
Please feel free to drop the Fixes tag -- I generally add them for
things that get actually rendered in the documentation, since the stable
team sometimes picks even typos, but it is of course not an bug on a
kernel feature, of course.

 rust/kernel/net/phy/reg.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/net/phy/reg.rs b/rust/kernel/net/phy/reg.rs
index a7db0064cb7d..4e8b58711bae 100644
--- a/rust/kernel/net/phy/reg.rs
+++ b/rust/kernel/net/phy/reg.rs
@@ -34,10 +34,10 @@ pub trait Sealed {}
 ///
 ///     // Checks the link status as reported by registers in the C22 namespace
 ///     // and updates current link state.
-///     dev.genphy_read_status::<phy::C22>();
+///     dev.genphy_read_status::<C22>();
 ///     // Checks the link status as reported by registers in the C45 namespace
 ///     // and updates current link state.
-///     dev.genphy_read_status::<phy::C45>();
+///     dev.genphy_read_status::<C45>();
 /// }
 /// ```
 pub trait Register: private::Sealed {

base-commit: e9a6fb0bcdd7609be6969112f3fbfcce3b1d4a7c
--
2.51.2

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

[Miguel Ojeda]

This example can easily be made buildable, thus do so.

Making examples buildable prevents issues like the one fixed in the
previous commit.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/net/phy/reg.rs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/net/phy/reg.rs b/rust/kernel/net/phy/reg.rs
index 4e8b58711bae..165bbff93e53 100644
--- a/rust/kernel/net/phy/reg.rs
+++ b/rust/kernel/net/phy/reg.rs
@@ -25,7 +25,16 @@ pub trait Sealed {}
 ///
 /// # Examples
 ///
-/// ```ignore
+/// ```
+/// # use kernel::net::phy::{
+/// #     self,
+/// #     Device,
+/// #     reg::{
+/// #         C22,
+/// #         C45,
+/// #         Mmd, //
+/// #     }, //
+/// # };
 /// fn link_change_notify(dev: &mut Device) {
 ///     // read C22 BMCR register
 ///     dev.read(C22::BMCR);
-- 
2.51.2

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

[FUJITA Tomonori]

On Mon, 10 Nov 2025 13:22:22 +0100
Miguel Ojeda <ojeda@kernel.org> wrote:

> This example can easily be made buildable, thus do so.
> 
> Making examples buildable prevents issues like the one fixed in the
> previous commit.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
>  rust/kernel/net/phy/reg.rs | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/rust/kernel/net/phy/reg.rs b/rust/kernel/net/phy/reg.rs
> index 4e8b58711bae..165bbff93e53 100644
> --- a/rust/kernel/net/phy/reg.rs
> +++ b/rust/kernel/net/phy/reg.rs
> @@ -25,7 +25,16 @@ pub trait Sealed {}
>  ///
>  /// # Examples
>  ///
> -/// ```ignore
> +/// ```
> +/// # use kernel::net::phy::{
> +/// #     self,
> +/// #     Device,
> +/// #     reg::{
> +/// #         C22,
> +/// #         C45,
> +/// #         Mmd, //
> +/// #     }, //
> +/// # };
>  /// fn link_change_notify(dev: &mut Device) {
>  ///     // read C22 BMCR register
>  ///     dev.read(C22::BMCR);

I think that some code begin lines with # for use lines in a "#
Examples" section, while others do not. Which style is recommended?

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@gmail.com> 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

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

[FUJITA Tomonori]

On Tue, 11 Nov 2025 22:02:26 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> 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.

Understood, thanks!

Then I don't think that the imports in this example are important so
please add:

Reviewed-by: FUJITA Tomonori <fujita.tomonori@gmail.com>

[PATCH 3/3] rust: net: phy: follow usual comment conventions

[Miguel Ojeda]

Examples should aim to follow the usual conventions, which makes
documentation more consistent with code and itself, and it should also
help newcomers learn them more easily.

Thus change the comments to follow them.

Link: https://docs.kernel.org/rust/coding-guidelines.html#comments
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/net/phy/reg.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/net/phy/reg.rs b/rust/kernel/net/phy/reg.rs
index 165bbff93e53..5a7b808915f9 100644
--- a/rust/kernel/net/phy/reg.rs
+++ b/rust/kernel/net/phy/reg.rs
@@ -36,9 +36,9 @@ pub trait Sealed {}
 /// #     }, //
 /// # };
 /// fn link_change_notify(dev: &mut Device) {
-///     // read C22 BMCR register
+///     // Read C22 BMCR register.
 ///     dev.read(C22::BMCR);
-///     // read C45 PMA/PMD control 1 register
+///     // Read C45 PMA/PMD control 1 register.
 ///     dev.read(C45::new(Mmd::PMAPMD, 0));
 ///
 ///     // Checks the link status as reported by registers in the C22 namespace
-- 
2.51.2

Re: [PATCH 3/3] rust: net: phy: follow usual comment conventions

[FUJITA Tomonori]

On Mon, 10 Nov 2025 13:22:23 +0100
Miguel Ojeda <ojeda@kernel.org> wrote:

> Examples should aim to follow the usual conventions, which makes
> documentation more consistent with code and itself, and it should also
> help newcomers learn them more easily.
> 
> Thus change the comments to follow them.
> 
> Link: https://docs.kernel.org/rust/coding-guidelines.html#comments
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
>  rust/kernel/net/phy/reg.rs | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Reviewed-by: FUJITA Tomonori <fujita.tomonori@gmail.com>

Re: [PATCH 1/3] rust: net: phy: fix example's references to `C{22,45}`

[Andrew Lunn]

On Mon, Nov 10, 2025 at 01:22:21PM +0100, Miguel Ojeda wrote:
> The example refers to `phy::C{22,45}`, but there are no such items --
> they are within `reg`.
> 
> Thus fix it.
> 
> Fixes: 5114e05a3cfa ("rust: net::phy unified genphy_read_status function for C22 and C45 registers")
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> Please feel free to drop the Fixes tag -- I generally add them for
> things that get actually rendered in the documentation, since the stable
> team sometimes picks even typos, but it is of course not an bug on a
> kernel feature, of course.

netdev generally does backport documentation fixed. There are a lot of
developers stuck on LTS trees.

Please submit this to net, and include the Fixes tag.

	Andrew

Re: [PATCH 1/3] rust: net: phy: fix example's references to `C{22,45}`

[FUJITA Tomonori]

On Mon, 10 Nov 2025 13:22:21 +0100
Miguel Ojeda <ojeda@kernel.org> wrote:

> The example refers to `phy::C{22,45}`, but there are no such items --
> they are within `reg`.
> 
> Thus fix it.
> 
> Fixes: 5114e05a3cfa ("rust: net::phy unified genphy_read_status function for C22 and C45 registers")
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Reviewed-by: FUJITA Tomonori <fujita.tomonori@gmail.com>