[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20240904204347.168520-15-ojeda@kernel.org>
Date: Wed, 4 Sep 2024 22:43:42 +0200
From: Miguel Ojeda <ojeda@...nel.org>
To: Miguel Ojeda <ojeda@...nel.org>,
Alex Gaynor <alex.gaynor@...il.com>,
Wedson Almeida Filho <wedsonaf@...il.com>
Cc: Boqun Feng <boqun.feng@...il.com>,
Gary Guo <gary@...yguo.net>,
Björn Roy Baron <bjorn3_gh@...tonmail.com>,
Benno Lossin <benno.lossin@...ton.me>,
Andreas Hindborg <a.hindborg@...sung.com>,
Alice Ryhl <aliceryhl@...gle.com>,
Trevor Gross <tmgross@...ch.edu>,
rust-for-linux@...r.kernel.org,
linux-kernel@...r.kernel.org,
patches@...ts.linux.dev
Subject: [PATCH 14/19] rust: provide proper code documentation titles
Rust 1.82.0's Clippy is introducing [1][2] a new warn-by-default lint,
`too_long_first_doc_paragraph` [3], which is intended to catch titles
of code documentation items that are too long (likely because no title
was provided and the item documentation starts with a paragraph).
This lint does not currently trigger anywhere, but it does detect a couple
cases we had in private cases if checking for private items gets enabled
(which we will do in the next commit):
error: first doc comment paragraph is too long
--> rust/kernel/init/__internal.rs:18:1
|
18 | / /// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this
19 | | /// type, since the closure needs to fulfill the same safety requirement as the
20 | | /// `__pinned_init`/`__init` functions.
| |_
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph
= note: `-D clippy::too-long-first-doc-paragraph` implied by `-D warnings`
= help: to override `-D warnings` add `#[allow(clippy::too_long_first_doc_paragraph)]`
error: first doc comment paragraph is too long
--> rust/kernel/sync/arc/std_vendor.rs:3:1
|
3 | / //! The contents of this file come from the Rust standard library, hosted in
4 | | //! the <https://github.com/rust-lang/rust> repository, licensed under
5 | | //! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,
6 | | //! see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>.
| |_
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph
Thus clean the two instances we hit and enable the lint.
In addition, since we have a second `std_vendor.rs` file with a similar
header, do the same there too (even if that one does not trigger the lint,
because it is `doc(hidden)`).
Link: https://github.com/rust-lang/rust/pull/129531 [1]
Link: https://github.com/rust-lang/rust-clippy/pull/12993 [2]
Link: https://rust-lang.github.io/rust-clippy/master/index.html#/too_long_first_doc_paragraph [3]
Signed-off-by: Miguel Ojeda <ojeda@...nel.org>
---
rust/kernel/init/__internal.rs | 7 ++++---
rust/kernel/std_vendor.rs | 2 ++
rust/kernel/sync/arc/std_vendor.rs | 2 ++
3 files changed, 8 insertions(+), 3 deletions(-)
diff --git a/rust/kernel/init/__internal.rs b/rust/kernel/init/__internal.rs
index 29f4fd00df3d..163eb072f296 100644
--- a/rust/kernel/init/__internal.rs
+++ b/rust/kernel/init/__internal.rs
@@ -15,9 +15,10 @@
/// [this table]: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns
pub(super) type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
-/// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this
-/// type, since the closure needs to fulfill the same safety requirement as the
-/// `__pinned_init`/`__init` functions.
+/// Module-internal type implementing `PinInit` and `Init`.
+///
+/// It is unsafe to create this type, since the closure needs to fulfill the same safety
+/// requirement as the `__pinned_init`/`__init` functions.
pub(crate) struct InitClosure<F, T: ?Sized, E>(pub(crate) F, pub(crate) Invariant<(E, T)>);
// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the
diff --git a/rust/kernel/std_vendor.rs b/rust/kernel/std_vendor.rs
index 085b23312c65..d59e4cf4b252 100644
--- a/rust/kernel/std_vendor.rs
+++ b/rust/kernel/std_vendor.rs
@@ -1,5 +1,7 @@
// SPDX-License-Identifier: Apache-2.0 OR MIT
+//! Rust standard library vendored code.
+//!
//! The contents of this file come from the Rust standard library, hosted in
//! the <https://github.com/rust-lang/rust> repository, licensed under
//! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,
diff --git a/rust/kernel/sync/arc/std_vendor.rs b/rust/kernel/sync/arc/std_vendor.rs
index a66a0c2831b3..11b3f4ecca5f 100644
--- a/rust/kernel/sync/arc/std_vendor.rs
+++ b/rust/kernel/sync/arc/std_vendor.rs
@@ -1,5 +1,7 @@
// SPDX-License-Identifier: Apache-2.0 OR MIT
+//! Rust standard library vendored code.
+//!
//! The contents of this file come from the Rust standard library, hosted in
//! the <https://github.com/rust-lang/rust> repository, licensed under
//! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,
--
2.46.0
Powered by blists - more mailing lists