rust: prepare doctests

In preparation for enabling them later.

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

rust/bindgen_parameters

@@ -8,3 +8,6 @@
 # If SMP is disabled, `arch_spinlock_t` is defined as a ZST which triggers a Rust
 # warning. We don't need to peek into it anyway.
 --opaque-type spinlock
+
+# `seccomp`'s comment gets understood as a doctest
+--no-doc-comments

rust/kernel/build_assert.rs

@@ -9,7 +9,8 @@
 /// be called, a build error will be triggered.
 ///
 /// # Examples
-/// ```no_run
+/// ```
+/// # use kernel::build_error;
 /// #[inline]
 /// fn foo(a: usize) -> usize {
 ///     a.checked_add(1).unwrap_or_else(|| build_error!("overflow"))
@@ -38,7 +39,8 @@ macro_rules! build_error {
 /// These examples show that different types of [`assert!`] will trigger errors
 /// at different stage of compilation. It is preferred to err as early as
 /// possible, so [`static_assert!`] should be used whenever possible.
-/// ```no_run
+/// ```compile_fail
+/// # use kernel::prelude::*;
 /// fn foo() {
 ///     static_assert!(1 > 1); // Compile-time error
 ///     build_assert!(1 > 1); // Build-time error
@@ -49,6 +51,7 @@ macro_rules! build_error {
 /// When the condition refers to generic parameters or parameters of an inline function,
 /// [`static_assert!`] cannot be used. Use `build_assert!` in this scenario.
 /// ```no_run
+/// # use kernel::prelude::*;
 /// fn foo<const N: usize>() {
 ///     // `static_assert!(N > 1);` is not allowed
 ///     build_assert!(N > 1); // Build-time check

rust/kernel/error.rs

@@ -190,7 +190,10 @@ where
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```ignore
+/// # use kernel::from_kernel_result;
+/// # use kernel::c_types;
+/// # use kernel::bindings;
 /// unsafe extern "C" fn probe_callback(
 ///     pdev: *mut bindings::platform_device,
 /// ) -> c_types::c_int {
@@ -219,7 +222,11 @@ macro_rules! from_kernel_result {
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```ignore
+/// # use kernel::prelude::*;
+/// # use kernel::from_kernel_err_ptr;
+/// # use kernel::c_types;
+/// # use kernel::bindings;
 /// fn devm_platform_ioremap_resource(
 ///     pdev: &mut PlatformDevice,
 ///     index: u32,

rust/kernel/lib.rs

@@ -155,6 +155,8 @@ impl<'a> Drop for KParamGuard<'a> {
 /// # Example
 ///
 /// ```
+/// # use kernel::prelude::*;
+/// # use kernel::offset_of;
 /// struct Test {
 ///     a: u64,
 ///     b: u32,
@@ -193,6 +195,8 @@ macro_rules! offset_of {
 /// # Example
 ///
 /// ```
+/// # use kernel::prelude::*;
+/// # use kernel::container_of;
 /// struct Test {
 ///     a: u64,
 ///     b: u32,

rust/kernel/module_param.rs

@@ -210,7 +210,7 @@ macro_rules! impl_module_param {
 /// Generate a static [`kernel_param_ops`](../../../include/linux/moduleparam.h) struct.
 ///
 /// # Example
-/// ```rust
+/// ```ignore
 /// make_param_ops!(
 ///     /// Documentation for new param ops.
 ///     PARAM_OPS_MYTYPE, // Name for the static.

rust/kernel/prelude.rs

@@ -7,7 +7,7 @@
 //!
 //! # Examples
 //!
-//! ```rust,no_run
+//! ```
 //! use kernel::prelude::*;
 //! ```
 

rust/kernel/print.rs

@@ -163,6 +163,7 @@ pub fn call_printk_cont(args: fmt::Arguments<'_>) {
 ///
 /// Public but hidden since it should only be used from public macros.
 #[doc(hidden)]
+#[cfg(not(testlib))]
 #[macro_export]
 macro_rules! print_macro (
     // The non-continuation cases (most of them, e.g. `INFO`).
@@ -189,6 +190,15 @@ macro_rules! print_macro (
     );
 );
 
+// Stub for doctests
+#[cfg(testlib)]
+#[macro_export]
+macro_rules! print_macro (
+    ($format_string:path, $e:expr, $($arg:tt)+) => (
+        ()
+    );
+);
+
 // We could use a macro to generate these macros. However, doing so ends
 // up being a bit ugly: it requires the dollar token trick to escape `$` as
 // well as playing with the `doc` attribute. Furthermore, they cannot be easily
@@ -213,6 +223,7 @@ macro_rules! print_macro (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_emerg!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -237,6 +248,7 @@ macro_rules! pr_emerg (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_alert!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -261,6 +273,7 @@ macro_rules! pr_alert (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_crit!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -285,6 +298,7 @@ macro_rules! pr_crit (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_err!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -309,6 +323,7 @@ macro_rules! pr_err (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_warn!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -333,6 +348,7 @@ macro_rules! pr_warn (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_notice!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -357,6 +373,7 @@ macro_rules! pr_notice (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// pr_info!("hello {}\n", "there");
 /// ```
 #[macro_export]
@@ -382,6 +399,8 @@ macro_rules! pr_info (
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
+/// # use kernel::pr_cont;
 /// pr_info!("hello");
 /// pr_cont!(" {}\n", "there");
 /// ```

rust/kernel/static_assert.rs

@@ -15,6 +15,7 @@
 /// # Examples
 ///
 /// ```
+/// # use kernel::prelude::*;
 /// static_assert!(42 > 24);
 /// static_assert!(core::mem::size_of::<u8>() == 1);
 ///

rust/kernel/str.rs

@@ -19,7 +19,9 @@ pub type BStr = [u8];
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```
+/// # use kernel::b_str;
+/// # use kernel::str::BStr;
 /// const MY_BSTR: &'static BStr = b_str!("My awesome BStr!");
 /// ```
 #[macro_export]
@@ -242,7 +244,9 @@ where
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```
+/// # use kernel::c_str;
+/// # use kernel::str::CStr;
 /// const MY_CSTR: &'static CStr = c_str!("My awesome CStr!");
 /// ```
 #[macro_export]

rust/kernel/sync/locked_by.rs

@@ -24,8 +24,8 @@ use core::{cell::UnsafeCell, ops::Deref, ptr};
 /// locked; we enforce at run time that the right `InnerDirectory` is locked.
 ///
 /// ```
-/// use super::Mutex;
-/// use alloc::{string::String, vec::Vec};
+/// # use kernel::prelude::*;
+/// use kernel::sync::{LockedBy, Mutex};
 ///
 /// struct InnerFile {
 ///     bytes_used: u64,

rust/kernel/sync/mod.rs

@@ -7,14 +7,15 @@
 //!
 //! # Example
 //!
-//! ```
-//! fn test() {
-//!     // SAFETY: `init` is called below.
-//!     let data = alloc::sync::Arc::pin(unsafe { Mutex::new(0) });
-//!     mutex_init!(data.as_ref(), "test::data");
-//!     *data.lock() = 10;
-//!     pr_info!("{}\n", *data.lock());
-//! }
+//! ```no_run
+//! # use kernel::prelude::*;
+//! # use kernel::mutex_init;
+//! # use kernel::sync::Mutex;
+//! // SAFETY: `init` is called below.
+//! let data = alloc::sync::Arc::pin(unsafe { Mutex::new(0) });
+//! mutex_init!(data.as_ref(), "test::data");
+//! *data.lock() = 10;
+//! pr_info!("{}\n", *data.lock());
 //! ```
 
 use crate::str::CStr;

rust/kernel/types.rs

@@ -105,6 +105,8 @@ impl<T: PointerWrapper + Deref> PointerWrapper for Pin<T> {
 /// In the example below, we have multiple exit paths and we want to log regardless of which one is
 /// taken:
 /// ```
+/// # use kernel::prelude::*;
+/// # use kernel::ScopeGuard;
 /// fn example1(arg: bool) {
 ///     let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
 ///
@@ -119,6 +121,8 @@ impl<T: PointerWrapper + Deref> PointerWrapper for Pin<T> {
 /// In the example below, we want to log the same message on all early exits but a different one on
 /// the main exit path:
 /// ```
+/// # use kernel::prelude::*;
+/// # use kernel::ScopeGuard;
 /// fn example2(arg: bool) {
 ///     let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
 ///

rust/macros/lib.rs

@@ -22,7 +22,7 @@ use proc_macro::TokenStream;
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```ignore
 /// use kernel::prelude::*;
 ///
 /// module!{
@@ -108,7 +108,7 @@ pub fn module(ts: TokenStream) -> TokenStream {
 ///
 /// # Examples
 ///
-/// ```rust,no_run
+/// ```ignore
 /// use kernel::prelude::*;
 ///
 /// module_misc_device! {