diff mbox series

[1/6] rust: init: make doctests compilable/testable

Message ID 20230614180837.630180-2-ojeda@kernel.org
State New
Headers
Series KUnit integration for Rust doctests |

Commit Message

Miguel Ojeda June 14, 2023, 6:08 p.m. UTC 
  Rust documentation tests are going to be build/run-tested
with the KUnit integration added in a future patch, thus
update them to make them compilable/testable so that we
may start enforcing it.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/init.rs | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

Comments

Alice Ryhl June 14, 2023, 8:32 p.m. UTC | #1 
Miguel Ojeda <ojeda@kernel.org> writes:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Martin Rodriguez Reboredo June 15, 2023, 1:03 a.m. UTC | #2 
On 6/14/23 15:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
> [...]
>   //! #     pub unsafe fn destroy_foo(_ptr: *mut foo) {}
>   //! #     pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
>   //! # }
> +//! # trait FromErrno {
> +//! #     fn from_errno(errno: core::ffi::c_int) -> Error {
> +//! #         // Dummy error that can be constructed outside the `kernel` crate.
> +//! #         Error::from(core::fmt::Error)
> +//! #     }
> +//! # }
> +//! # impl FromErrno for Error {}
>   //! /// # Invariants
>   //! ///
>   //! /// `foo` is always initialized
> [...]

Little question, what's the purpose of `FromErrno` here?
Miguel Ojeda June 15, 2023, 9:31 a.m. UTC | #3 
On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
<yakoyoku@gmail.com> wrote:
>
> Little question, what's the purpose of `FromErrno` here?

It was because `Error::from_errno` is `pub(crate)` in the `kernel`
crate. I should have added a comment -- my bad! :)

If we decided to make it `pub` eventually, then this `FromErrno` hack
can be removed.

Cheers,
Miguel
Martin Rodriguez Reboredo June 15, 2023, 1:33 p.m. UTC | #4 
On 6/15/23 06:31, Miguel Ojeda wrote:
> On Thu, Jun 15, 2023 at 5:52 AM Martin Rodriguez Reboredo
> <yakoyoku@gmail.com> wrote:
>>
>> Little question, what's the purpose of `FromErrno` here?
> 
> It was because `Error::from_errno` is `pub(crate)` in the `kernel`
> crate. I should have added a comment -- my bad! :)
> 
> If we decided to make it `pub` eventually, then this `FromErrno` hack
> can be removed.
> 
> Cheers,
> Miguel

I think that `FromErrno` should be made public the moment when more
doctests rely upon it, until then.

Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Vincenzo Palazzo June 15, 2023, 11:47 p.m. UTC | #5 
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---


Reviewed-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
David Gow June 16, 2023, 4:51 a.m. UTC | #6 
On Thu, 15 Jun 2023 at 02:09, Miguel Ojeda <ojeda@kernel.org> wrote:
>
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
>
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---

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

Cheers,
-- David
Björn Roy Baron June 16, 2023, 11:12 a.m. UTC | #7 
------- Original Message -------
On Wednesday, June 14th, 2023 at 20:08, Miguel Ojeda <ojeda@kernel.org> wrote:

> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
> ---
>  rust/kernel/init.rs | 25 ++++++++++++++++---------
>  1 file changed, 16 insertions(+), 9 deletions(-)
> 
> diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
> index b4332a4ec1f4..1073515ed40e 100644
> --- a/rust/kernel/init.rs
> +++ b/rust/kernel/init.rs
> @@ -120,14 +120,23 @@
>  //!   `slot` gets called.
>  //!
>  //! ```rust
> -//! use kernel::{prelude::*, init};
> +//! # #![allow(unreachable_pub, clippy::disallowed_names)]
> +//! use kernel::{prelude::*, init, types::Opaque};
>  //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin};
>  //! # mod bindings {
> +//! #     #![allow(non_camel_case_types)]
>  //! #     pub struct foo;
>  //! #     pub unsafe fn init_foo(_ptr: *mut foo) {}
>  //! #     pub unsafe fn destroy_foo(_ptr: *mut foo) {}
>  //! #     pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
>  //! # }
> +//! # trait FromErrno {
> +//! #     fn from_errno(errno: core::ffi::c_int) -> Error {
> +//! #         // Dummy error that can be constructed outside the `kernel` crate.
> +//! #         Error::from(core::fmt::Error)
> +//! #     }
> +//! # }
> +//! # impl FromErrno for Error {}
>  //! /// # Invariants
>  //! ///
>  //! /// `foo` is always initialized
> @@ -158,7 +167,7 @@
>  //!                 if err != 0 {
>  //!                     // Enabling has failed, first clean up the foo and then return the error.
>  //!                     bindings::destroy_foo(Opaque::raw_get(foo));
> -//!                     return Err(Error::from_kernel_errno(err));
> +//!                     return Err(Error::from_errno(err));
>  //!                 }
>  //!
>  //!                 // All fields of `RawFoo` have been initialized, since `_p` is a ZST.
> @@ -226,8 +235,7 @@
>  ///
>  /// ```rust
>  /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
> -/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
> -/// # use macros::pin_data;
> +/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
>  /// # use core::pin::Pin;
>  /// #[pin_data]
>  /// struct Foo {
> @@ -277,7 +285,7 @@ macro_rules! stack_pin_init {
>  ///
>  /// # Examples
>  ///
> -/// ```rust
> +/// ```rust,ignore
>  /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
>  /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
>  /// # use macros::pin_data;
> @@ -303,7 +311,7 @@ macro_rules! stack_pin_init {
>  /// pr_info!("a: {}", &*foo.a.lock());
>  /// ```
>  ///
> -/// ```rust
> +/// ```rust,ignore
>  /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
>  /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
>  /// # use macros::pin_data;
> @@ -513,8 +521,7 @@ macro_rules! stack_try_pin_init {
>  /// For instance:
>  ///
>  /// ```rust
> -/// # use kernel::pin_init;
> -/// # use macros::pin_data;
> +/// # use kernel::{macros::pin_data, pin_init};
>  /// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
>  /// #[pin_data]
>  /// struct Buf {
> @@ -841,7 +848,7 @@ macro_rules! init {
>  /// # Examples
>  ///
>  /// ```rust
> -/// use kernel::{init::PinInit, error::Error, InPlaceInit};
> +/// use kernel::{init::{PinInit, zeroed}, error::Error};
>  /// struct BigBuf {
>  ///     big: Box<[u8; 1024 * 1024 * 1024]>,
>  ///     small: [u8; 1024 * 1024],
> -- 
> 2.41.0

Reviewed-by: Björn Roy Baron <bjorn3_gh@protonmail.com>
Benno Lossin June 25, 2023, 10:13 a.m. UTC | #8 
On 6/14/23 20:08, Miguel Ojeda wrote:
> Rust documentation tests are going to be build/run-tested
> with the KUnit integration added in a future patch, thus
> update them to make them compilable/testable so that we
> may start enforcing it.
> 
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Reviewed-by: Benno Lossin <benno.lossin@proton.me>
diff mbox series

Patch

diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index b4332a4ec1f4..1073515ed40e 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -120,14 +120,23 @@ 
 //!   `slot` gets called.
 //!
 //! ```rust
-//! use kernel::{prelude::*, init};
+//! # #![allow(unreachable_pub, clippy::disallowed_names)]
+//! use kernel::{prelude::*, init, types::Opaque};
 //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin};
 //! # mod bindings {
+//! #     #![allow(non_camel_case_types)]
 //! #     pub struct foo;
 //! #     pub unsafe fn init_foo(_ptr: *mut foo) {}
 //! #     pub unsafe fn destroy_foo(_ptr: *mut foo) {}
 //! #     pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
 //! # }
+//! # trait FromErrno {
+//! #     fn from_errno(errno: core::ffi::c_int) -> Error {
+//! #         // Dummy error that can be constructed outside the `kernel` crate.
+//! #         Error::from(core::fmt::Error)
+//! #     }
+//! # }
+//! # impl FromErrno for Error {}
 //! /// # Invariants
 //! ///
 //! /// `foo` is always initialized
@@ -158,7 +167,7 @@ 
 //!                 if err != 0 {
 //!                     // Enabling has failed, first clean up the foo and then return the error.
 //!                     bindings::destroy_foo(Opaque::raw_get(foo));
-//!                     return Err(Error::from_kernel_errno(err));
+//!                     return Err(Error::from_errno(err));
 //!                 }
 //!
 //!                 // All fields of `RawFoo` have been initialized, since `_p` is a ZST.
@@ -226,8 +235,7 @@ 
 ///
 /// ```rust
 /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
-/// # use kernel::{init, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
-/// # use macros::pin_data;
+/// # use kernel::{init, macros::pin_data, pin_init, stack_pin_init, init::*, sync::Mutex, new_mutex};
 /// # use core::pin::Pin;
 /// #[pin_data]
 /// struct Foo {
@@ -277,7 +285,7 @@  macro_rules! stack_pin_init {
 ///
 /// # Examples
 ///
-/// ```rust
+/// ```rust,ignore
 /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
 /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
 /// # use macros::pin_data;
@@ -303,7 +311,7 @@  macro_rules! stack_pin_init {
 /// pr_info!("a: {}", &*foo.a.lock());
 /// ```
 ///
-/// ```rust
+/// ```rust,ignore
 /// # #![allow(clippy::disallowed_names, clippy::new_ret_no_self)]
 /// # use kernel::{init, pin_init, stack_try_pin_init, init::*, sync::Mutex, new_mutex};
 /// # use macros::pin_data;
@@ -513,8 +521,7 @@  macro_rules! stack_try_pin_init {
 /// For instance:
 ///
 /// ```rust
-/// # use kernel::pin_init;
-/// # use macros::pin_data;
+/// # use kernel::{macros::pin_data, pin_init};
 /// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
 /// #[pin_data]
 /// struct Buf {
@@ -841,7 +848,7 @@  macro_rules! init {
 /// # Examples
 ///
 /// ```rust
-/// use kernel::{init::PinInit, error::Error, InPlaceInit};
+/// use kernel::{init::{PinInit, zeroed}, error::Error};
 /// struct BigBuf {
 ///     big: Box<[u8; 1024 * 1024 * 1024]>,
 ///     small: [u8; 1024 * 1024],