rust: allow `unreachable_pub` for doctests
Subsystems (5)
Miguel Ojeda
maintainerPATCH 1/2 rust: allow `unreachable_pub` for doctests
Examples (i.e. doctests) may want to show public items such as structs, thus the unreachable_pub warning is not very helpful.
Thus allow it for all doctests.
In addition, remove it from the existing expects we have in a couple doctests.
--- rust/kernel/init.rs | 2 +- rust/kernel/types.rs | 2 +- scripts/rustdoc_test_gen.rs | 1 + 3 files changed, 3 insertions(+), 2 deletions(-)
rust/kernel/init.rs +1 -1
@@ -67,7 +67,7 @@//! ``` //! //! ```rust -//! # #![expect(unreachable_pub, clippy::disallowed_names)] +//! # #![expect(clippy::disallowed_names)] //! use kernel::{prelude::*, types::Opaque}; //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; //! # mod bindings {
rust/kernel/types.rs +1 -1
@@ -289,7 +289,7 @@ fn drop(&mut self) {/// # Examples /// /// ``` -/// # #![expect(unreachable_pub, clippy::disallowed_names)] +/// # #![expect(clippy::disallowed_names)] /// use kernel::types::Opaque; /// # // Emulate a C struct binding which is from C, maybe uninitialized or not, only the C side /// # // knows.
scripts/rustdoc_test_gen.rs +1 -0
@@ -208,6 +208,7 @@ macro_rules! assert_eq {{#[allow(unused)] static __DOCTEST_ANCHOR:i32 = ::core::line!()as i32 + {body_offset} +1 ; {{ +#![allow(unreachable_pub)] {body}main (); }}
base-commit: e9a6fb0bcdd7609be6969112f3fbfcce3b1d4a7c
Signature · 1 line
2.51.2
Miguel Ojeda
maintainerPATCH 2/2 rust: device: make example buildable
This example can easily be made buildable, thus do so.
It would have triggered an unreachable_pub warning without the previous commit.
--- rust/kernel/device.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-)
rust/kernel/device.rs +10 -1
@@ -67,7 +67,16 @@/// /// A bus specific device should be defined as follows. /// -/// ```ignore +/// ``` +/// # use core::marker::PhantomData; +/// # use kernel::{ +/// # device, +/// # types::Opaque, // +/// # }; +/// # mod bindings { +/// # #[expect(non_camel_case_types)] +/// # pub struct bus_device_type; +/// # } /// #[repr(transparent)] /// pub struct Device<Ctx: device::DeviceContext = device::Normal>( /// Opaque<bindings::bus_device_type>,
Signature · 1 line
2.51.2
Re: [PATCH 2/2] rust: device: make example buildable
Quoted 6 lines · Miguel Ojeda
This example can easily be made buildable, thus do so.
It would have triggered an
unreachable_pubwarning without the previous commit.Signed-off-by Miguel Ojeda <[email protected]>
Quoted 28 lines
rust/kernel/device.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-)rust/kernel/device.rs +10
-1@@ -67,7 +67,16 @@/// /// A bus specific device should be defined as follows. /// -/// ```ignore +/// ``` +/// # use core::marker::PhantomData; +/// # use kernel::{ +/// # device, +/// # types::Opaque, // +/// # }; +/// # mod bindings { +/// # #[expect(non_camel_case_types)] +/// # pub struct bus_device_type; +/// # } /// #[repr(transparent)] /// pub struct Device<Ctx: device::DeviceContext = device::Normal>( /// Opaque<bindings::bus_device_type>, Signature · 1 line
2.51.2
Re: [PATCH 2/2] rust: device: make example buildable
In reply to Miguel OjedaQuoted 8 lines · Miguel Ojeda
This example can easily be made buildable, thus do so.
It would have triggered an
unreachable_pubwarning without the previous commit.Signed-off-by Miguel Ojeda <[email protected]>---
Cheers,
-- David
Re: [PATCH 2/2] rust: device: make example buildable
In reply to Miguel OjedaQuoted 7 lines · Miguel Ojeda
This example can easily be made buildable, thus do so.
It would have triggered an
unreachable_pubwarning without the previous commit.Signed-off-by Miguel Ojeda <[email protected]>
Greg et al.: a quick Acked-by would be appreciated.
I can also pick the first patch without this one if preferred.
Thanks!
Cheers,
Miguel
Re: [PATCH 2/2] rust: device: make example buildable
Quoted 4 lines · Miguel Ojeda
Quoted 3 lines · Miguel Ojeda
This example can easily be made buildable, thus do so.
Quoted 8 lines
Quoted 4 lines
It would have triggered an
unreachable_pubwarning without the previous commit.Signed-off-by Miguel Ojeda <[email protected]>Greg et al.: a quick Acked-by would be appreciated.
I can also pick the first patch without this one if preferred.
Quoted 11 lines · Miguel Ojeda
Examples (i.e. doctests) may want to show public items such as structs, thus the
unreachable_pubwarning is not very helpful.Thus allow it for all doctests.
In addition, remove it from the existing
expects we have in a couple doctests.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Miguel Ojeda <[email protected]>
Quoted 10 lines
rust/kernel/init.rs | 2 +- rust/kernel/types.rs | 2 +- scripts/rustdoc_test_gen.rs | 1 + 3 files changed, 3 insertions(+), 2 deletions(-)rust/kernel/init.rs +0
-0
rust/kernel/init.rs line 70
Quoted 5 lines
rust/kernel/init.rs +1
-1@@ -67,7 +67,7 @@//! ``` //! //! ```rust -//! # #![expect(unreachable_pub, clippy::disallowed_names)] +//! # #![expect(clippy::disallowed_names)]
Maybe we should also allow disallowed_names in doc tests?
Alice
Quoted 2 lines · Alice Ryhl
Maybe we should also allow
disallowed_namesin doc tests?
Not sure -- I thought it may point people to try to come up with better names in examples. On the other hand, for abstract facilities, it is true that there may not be good names anyway.
Cheers,
Miguel
Gary Guo
maintainerQuoted 33 lines · On Mon, 10 Nov 2025 11:53:16 +0000 Alice Ryhl <[email protected]> wrote:
Quoted 11 lines · Miguel Ojeda
Examples (i.e. doctests) may want to show public items such as structs, thus the
unreachable_pubwarning is not very helpful.Thus allow it for all doctests.
In addition, remove it from the existing
expects we have in a couple doctests.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Miguel Ojeda <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 10 lines
rust/kernel/init.rs | 2 +- rust/kernel/types.rs | 2 +- scripts/rustdoc_test_gen.rs | 1 + 3 files changed, 3 insertions(+), 2 deletions(-)rust/kernel/init.rs +0
-0rust/kernel/init.rs line 70
Quoted 5 lines
rust/kernel/init.rs +1
-1@@ -67,7 +67,7 @@//! ``` //! //! ```rust -//! # #![expect(unreachable_pub, clippy::disallowed_names)] +//! # #![expect(clippy::disallowed_names)] Maybe we should also allow
disallowed_namesin doc tests?
Quoted 1 line
Alice
+1 on allowing disallowed_names. I think for doc tests we should try to reduce false positives to make it easier to write them. We shouldn't try to enable all clippy lints on doc tests, especially that clippy doesn't run today on rustdocs at all.
Best,
Gary
Quoted 2 lines · Gary Guo
On Mon, 10 Nov 2025 11:53:16 +0000
Alice Ryhl <[email protected]> wrote:
...
Quoted 7 lines
Quoted 6 lines
rust/kernel/init.rs line 70
Quoted 2 lines
rust/kernel/init.rs +1
-1-//! # #![expect(unreachable_pub, clippy::disallowed_names)] +//! # #![expect(clippy::disallowed_names)] Maybe we should also allow
disallowed_namesin doc tests?Alice
Quoted 8 lines
+1 on allowing
disallowed_names. I think for doc tests we should try to reduce false positives to make it easier to write them. We shouldn't try to enable all clippy lints on doc tests, especially that clippy doesn't run today on rustdocs at all.Best,
Gary
After learning about disallowed_names ("foo", "bar" and others that are in fact classical documentation favorites), I also think it would be very nice to allow those in documentation.
thanks,
Signature · 1 line
John Hubbard
Quoted 4 lines · Gary Guo
We shouldn't
try to enable all clippy lints on doc tests, especially that clippy doesn't run today on rustdocs at all.
You mean on Cargo / userspace projects, right?
Yeah, I think they want to change that -- it is a part of the kernel build that works better than the usual Rust project, in the sense that Clippy is quite important to have in order to enforce things like `//
SAFETY: ...` comments.
Cheers,
Miguel
Quoted 11 lines · Miguel Ojeda
Examples (i.e. doctests) may want to show public items such as structs, thus the
unreachable_pubwarning is not very helpful.Thus allow it for all doctests.
In addition, remove it from the existing
expects we have in a couple doctests.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Miguel Ojeda <[email protected]>
Cheers,
Benno
Quoted 5 lines
--- rust/kernel/init.rs | 2 +- rust/kernel/types.rs | 2 +- scripts/rustdoc_test_gen.rs | 1 + 3 files changed, 3 insertions(+), 2 deletions(-)
Quoted 6 lines · Miguel Ojeda
Examples (i.e. doctests) may want to show public items such as structs, thus the
unreachable_pubwarning is not very helpful.Thus allow it for all doctests.
Quoted 7 lines
In addition, remove it from the existing
expects we have in a couple doctests.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Miguel Ojeda <[email protected]>---
Cheers,
-- David
Quoted 4 lines · Miguel Ojeda
Examples (i.e. doctests) may want to show public items such as structs, thus the
unreachable_pubwarning is not very helpful.
Quoted 8 lines
Thus allow it for all doctests.
In addition, remove it from the existing
expects we have in a couple doctests.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Miguel Ojeda <[email protected]>
Applied (this one only) to rust-next -- thanks everyone!
Cheers,
Miguel