Skip to contentSkip to conversation

rust: allow `unreachable_pub` for doctests

PATCH In review Miguel Ojeda 8 participants 14 messages Nov 10, 2025 – Nov 26, 2025

Subsystems (5)
Kselftest Driver core Rust KUnit +1 more subsystems
lore
Share & tools
lore

Miguel Ojeda

author maintainer
#0 lore raw

PATCH 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
index 4949047af8d7..e476d81c1a27 100644
@@ -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
index dc0a02f5c3cf..835824788506 100644
@@ -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
index c8f9dc2ab976..0e6a0542d1bd 100644
@@ -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
author maintainer
#1 lore raw

PATCH 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
index a849b7dde2fd..d00f4af507db 100644
@@ -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
reviewer Reviewed-by on v1 2/2
#2 lore raw

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_pub warning without the previous commit.

Quoted 28 lines
 rust/kernel/device.rs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)
rust/kernel/device.rs +10 -1
index a849b7dde2fd..d00f4af507db 100644
@@ -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
#4 lore raw

Re: [PATCH 2/2] rust: device: make example buildable

In reply to Miguel Ojeda
Quoted 7 lines · Miguel Ojeda

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

It would have triggered an unreachable_pub warning without the previous commit.

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

maintainer Acked-by
#5 lore raw

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_pub warning without the previous commit.

Greg et al.: a quick Acked-by would be appreciated.

I can also pick the first patch without this one if preferred.

reviewer Reviewed-by on v1 1/2
#6 lore raw
In reply to Miguel Ojeda
Quoted 11 lines · Miguel Ojeda

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.

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
index 4949047af8d7..e476d81c1a27 100644

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

#7 lore raw
Quoted 2 lines · Alice Ryhl

Maybe we should also allow disallowed_names in 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

maintainer
#8 lore raw
In reply to Alice Ryhl
Quoted 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_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.

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
index 4949047af8d7..e476d81c1a27 100644

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?

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

#9 lore raw
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_names in 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
#10 lore raw
In reply to Gary Guo
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

maintainer Acked-by on v1 1/2
#11 lore raw
In reply to Miguel Ojeda
Quoted 11 lines · Miguel Ojeda

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.

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(-)
Reviewed-by on v1 1/2
#12 lore raw
In reply to Miguel Ojeda
Quoted 6 lines · Miguel Ojeda

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.

Quoted 7 lines

In addition, remove it from the existing expects we have in a couple doctests.

---

Cheers,
-- David

#13 lore raw
In reply to Miguel Ojeda
Quoted 4 lines · Miguel Ojeda

Examples (i.e. doctests) may want to show public items such as structs, thus the unreachable_pub warning 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.

Applied (this one only) to rust-next -- thanks everyone!

Cheers,
Miguel