Introduced in Rust 1.82.0 [1], this lint ensures that the first line of
documentation is short. That is because those lines get rendered in the
html version of the docs directly next to the items and should therefore
be short.
Additionally, a short first sentence might help developers remember the
rest of the documentation if they have read it already before.
Reviewers have pointed this out manually on several occasions, thus
enable the lint.
Here is an example error fixed in the previous commit:
error: first doc comment paragraph is too long
--> rust/kernel/driver.rs:13:1
|
13 | / /// The [`RegistrationOps`] trait serves as generic interface for subsystems (e.g., PCI, Platform,
14 | | /// Amba, etc.) to provide the corresponding subsystem specific implementation to register /
15 | | /// unregister a driver of the particular type (`RegType`).
16 | | ///
17 | | /// For instance, the PCI subsystem would set `RegType` to `bindings::pci_driver` and call
| |_^
|
= 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: aborting due to 1 previous error
The exact length can be configured in the .clippy.toml if we need to do
so.
Link: https://github.com/rust-lang/rust-clippy/issues/12989 [1]
Signed-off-by: Benno Lossin <benno.lossin@xxxxxxxxx>
---
Makefile | 1 +
1 file changed, 1 insertion(+)
diff --git a/Makefile b/Makefile
index 9e0d63d9d94b..d00cbeb63714 100644
--- a/Makefile
+++ b/Makefile
@@ -486,6 +486,7 @@ export rust_common_flags := --edition=2021 \
-Wclippy::undocumented_unsafe_blocks \
-Wclippy::unnecessary_safety_comment \
-Wclippy::unnecessary_safety_doc \
+ -Wclippy::too-long-first-doc-paragraph \
-Wrustdoc::missing_crate_level_docs \
-Wrustdoc::unescaped_backticks
--
2.47.2
