[PATCH 1/2] rust: allow `unreachable_pub` for doctests

[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 `expect`s we have in a couple
doctests.

Suggested-by: Alice Ryhl <alic...@google.com>
Link: https://lore.kernel.org/rust-for-linux/aRG9Vjsa...@google.com/
Signed-off-by: Miguel Ojeda <oj...@kernel.org>
---
rust/kernel/init.rs | 2 +-
rust/kernel/types.rs | 2 +-
scripts/rustdoc_test_gen.rs | 1 +
3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index 4949047af8d7..e476d81c1a27 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -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 {
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index dc0a02f5c3cf..835824788506 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -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.
diff --git a/scripts/rustdoc_test_gen.rs b/scripts/rustdoc_test_gen.rs
index c8f9dc2ab976..0e6a0542d1bd 100644
--- a/scripts/rustdoc_test_gen.rs
+++ b/scripts/rustdoc_test_gen.rs
@@ -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
--
2.51.2

[Miguel Ojeda]

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

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

Signed-off-by: Miguel Ojeda <oj...@kernel.org>
---

rust/kernel/device.rs | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index a849b7dde2fd..d00f4af507db 100644
--- a/rust/kernel/device.rs
+++ b/rust/kernel/device.rs
@@ -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>,
--
2.51.2

[Alice Ryhl]

On Mon, Nov 10, 2025 at 12:35:27PM +0100, Miguel Ojeda wrote:
> 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 `expect`s we have in a couple
> doctests.
>
> Suggested-by: Alice Ryhl <alic...@google.com>
> Link: https://lore.kernel.org/rust-for-linux/aRG9Vjsa...@google.com/
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>

Reviewed-by: Alice Ryhl <alic...@google.com>

> rust/kernel/init.rs | 2 +-
> rust/kernel/types.rs | 2 +-
> scripts/rustdoc_test_gen.rs | 1 +
> 3 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
> index 4949047af8d7..e476d81c1a27 100644
> --- a/rust/kernel/init.rs
> +++ b/rust/kernel/init.rs
> @@ -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

[Alice Ryhl]

On Mon, Nov 10, 2025 at 12:35:28PM +0100, Miguel Ojeda wrote:
> This example can easily be made buildable, thus do so.
>
> It would have triggered an `unreachable_pub` warning without the previous
> commit.
>
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>

Reviewed-by: Alice Ryhl <alic...@google.com>

[Miguel Ojeda]

On Mon, Nov 10, 2025 at 12:53 PM Alice Ryhl <alic...@google.com> wrote:
>
> 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

[Gary Guo]

+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

[Benno Lossin]

On Mon Nov 10, 2025 at 12:35 PM CET, Miguel Ojeda wrote:
> 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 `expect`s we have in a couple
> doctests.
>
> Suggested-by: Alice Ryhl <alic...@google.com>
> Link: https://lore.kernel.org/rust-for-linux/aRG9Vjsa...@google.com/
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>

Acked-by: Benno Lossin <los...@kernel.org>

Cheers,
Benno

[John Hubbard]

On 11/10/25 5:38 AM, Gary Guo wrote:
> On Mon, 10 Nov 2025 11:53:16 +0000
> Alice Ryhl <alic...@google.com> wrote:

...

>>> -//! # #![expect(unreachable_pub, clippy::disallowed_names)]
>>> +//! # #![expect(clippy::disallowed_names)]
>>
>> Maybe we should also allow disallowed_names in doc tests?
>>
>> 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
>

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,
--
John Hubbard

[David Gow]

On Mon, 10 Nov 2025 at 19:35, Miguel Ojeda <oj...@kernel.org> wrote:
>
> 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 `expect`s we have in a couple
> doctests.
>
> Suggested-by: Alice Ryhl <alic...@google.com>
> Link: https://lore.kernel.org/rust-for-linux/aRG9Vjsa...@google.com/
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>
> ---

Reviewed-by: David Gow <davi...@google.com>

Cheers,
-- David

[David Gow]

On Mon, 10 Nov 2025 at 19:35, Miguel Ojeda <oj...@kernel.org> wrote:
>

> This example can easily be made buildable, thus do so.
>
> It would have triggered an `unreachable_pub` warning without the previous
> commit.
>
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>
> ---

[Miguel Ojeda]

On Mon, Nov 10, 2025 at 12:35 PM Miguel Ojeda <oj...@kernel.org> wrote:
>
> This example can easily be made buildable, thus do so.
>
> It would have triggered an `unreachable_pub` warning without the previous
> commit.
>
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>

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

[Miguel Ojeda]

On Mon, Nov 10, 2025 at 2:38 PM Gary Guo <ga...@garyguo.net> wrote:
>
> 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

[Miguel Ojeda]

On Mon, Nov 10, 2025 at 12:35 PM Miguel Ojeda <oj...@kernel.org> wrote:
>

> 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 `expect`s we have in a couple
> doctests.
>
> Suggested-by: Alice Ryhl <alic...@google.com>
> Link: https://lore.kernel.org/rust-for-linux/aRG9Vjsa...@google.com/
> Signed-off-by: Miguel Ojeda <oj...@kernel.org>

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

Cheers,
Miguel

[Greg Kroah-Hartman]

Acked-by: Greg Kroah-Hartman <gre...@linuxfoundation.org>