docs(oxc): enable clippy::too_long_first_doc_paragraph (#9237)

Cargo.toml

@@ -74,6 +74,7 @@ missing_const_for_fn = "allow"
 significant_drop_in_scrutinee = "warn"
 iter_on_single_items = "warn"
 unused_peekable = "warn"
+too_long_first_doc_paragraph = "warn"
 # cargo
 cargo = { level = "warn", priority = -1 }
 multiple_crate_versions = "allow"

crates/oxc_allocator/src/convert.rs

@@ -2,9 +2,10 @@
 
 use crate::{Allocator, Box};
 
-/// This trait works similarly to the standard library [`From`] trait, It comes with a similar
-/// implementation containing blanket implementation for [`IntoIn`], reflective implementation and a
-/// bunch of primitive conversions from Rust types to their arena equivalent.
+/// This trait works similarly to the standard library [`From`] trait.
+///
+/// It comes with a similar implementation containing blanket implementation for [`IntoIn`],
+/// reflective implementation and a bunch of primitive conversions from Rust types to their arena equivalent.
 pub trait FromIn<'a, T>: Sized {
     /// Converts to this type from the input type within the given `allocator`.
     fn from_in(value: T, allocator: &'a Allocator) -> Self;

crates/oxc_ecmascript/src/constant_evaluation/is_literal_value.rs

@@ -1,6 +1,8 @@
 use oxc_ast::ast::*;
 
-/// Returns true if this is a literal value. We define a literal value as any node that evaluates
+/// Returns true if this is a literal value.
+///
+/// We define a literal value as any node that evaluates
 /// to the same thing regardless of when or where it is evaluated. So `/xyz/` and `[3, 5]` are
 /// literals, but the name a is not.
 ///

crates/oxc_linter/src/config/rules.rs

@@ -41,7 +41,9 @@ impl OxlintRules {
     }
 }
 
-/// A fully qualified rule name, e.g. `eslint/no-console` or `react/rule-of-hooks`.
+/// A fully qualified rule name.
+///
+/// e.g. `eslint/no-console` or `react/rule-of-hooks`.
 /// Includes the plugin name, the rule name, and the configuration for the rule (if any).
 /// This does not imply the rule is known to the linter as that, only that it is configured.
 #[derive(Debug, Clone)]

crates/oxc_linter/src/context/mod.rs

@@ -21,11 +21,12 @@ use crate::{
 mod host;
 pub(crate) use host::ContextHost;
 
+/// Contains all of the state and context specific to this lint rule.
+///
+/// Includes information like the rule name, plugin name, and severity of the rule.
+/// It also has a reference to the shared linting data [`ContextHost`], which is the same for all rules.
 #[derive(Clone)]
 #[must_use]
-/// Contains all of the state and context specific to this lint rule. Includes information
-/// like the rule name, plugin name, and severity of the rule. It also has a reference to
-/// the shared linting data [`ContextHost`], which is the same for all rules.
 pub struct LintContext<'a> {
     /// Shared context independent of the rule being linted.
     parent: Rc<ContextHost<'a>>,

crates/oxc_macros/src/lib.rs

@@ -100,9 +100,10 @@ pub fn declare_oxc_lint_test(input: TokenStream) -> TokenStream {
     declare_oxc_lint::declare_oxc_lint(metadata)
 }
 
-/// Declare all lint rules in a single macro. This create the `RuleEnum` struct,
-/// which is effectively a compile-time v-table for all lint rules. This
-/// bypasses object-safety requirements and allows for compile-time dispatch
+/// Declare all lint rules in a single macro.
+///
+/// This create the `RuleEnum` struct, which is effectively a compile-time v-table for all lint rules.
+/// This bypasses object-safety requirements and allows for compile-time dispatch
 /// over a heterogeneous set of known lint rules.
 #[proc_macro]
 pub fn declare_all_lint_rules(input: TokenStream) -> TokenStream {

crates/oxc_parser/src/lexer/mod.rs

@@ -330,6 +330,7 @@ impl<'a> Lexer<'a> {
 }
 
 /// Call a closure while hinting to compiler that this branch is rarely taken.
+///
 /// "Cold trampoline function", suggested in:
 /// <https://users.rust-lang.org/t/is-cold-the-only-reliable-way-to-hint-to-branch-predictor/106509/2>
 #[cold]

crates/oxc_prettier/src/macros.rs

@@ -52,6 +52,8 @@ macro_rules! dynamic_text {
     }};
 }
 
+/// `group`
+///
 /// Mark a group of items which the printer should try to fit on one line.
 /// This is the basic command to tell the printer when to break.
 /// Groups are usually nested, and the printer will try to fit everything on one line,
@@ -103,6 +105,8 @@ macro_rules! group {
     }};
 }
 
+/// `conditional_group`
+///
 /// This should be used as last resort as it triggers an exponential complexity when nested.
 /// This will try to print the first alternative, if it fit use it, otherwise go to the next one and so on.
 /// The alternatives is an array of documents going from the least expanded (most flattened) representation first to the most expanded.
@@ -129,6 +133,8 @@ macro_rules! conditional_group {
     }};
 }
 
+/// `fill`
+///
 /// This is an alternative type of group which behaves like text layout:
 /// it's going to add a break whenever the next element doesn't fit in the line anymore.
 /// The difference with `group` is that it's not going to break all the separators, just the ones that are at the end of lines.
@@ -154,6 +160,8 @@ macro_rules! fill {
     }};
 }
 
+/// `if_break`
+///
 /// Print something if the current group or the current element of fill breaks and something else if it doesn't.
 /// `group_id` can be used to check another already printed group instead of the current group.
 ///
@@ -221,6 +229,7 @@ macro_rules! join {
 }
 
 /// Specify a line break.
+///
 /// If an expression fits on one line, the line break will be replaced with a space.
 /// Line breaks always indent the next line with the current level of indentation.
 /// <https://github.com/prettier/prettier/blob/3.4.2/commands.md#line>
@@ -262,6 +271,8 @@ macro_rules! hardline {
     }};
 }
 
+/// `literalline`
+///
 /// Specify a line break that is always included in the output and doesn't indent the next line.
 /// Also, unlike hardline, this kind of line break preserves trailing whitespace on the line it ends.
 /// This is used for template literals.
@@ -283,6 +294,8 @@ macro_rules! literalline {
     }};
 }
 
+/// `line_suffix_boundary`
+///
 /// In cases where you embed code inside of templates, comments shouldn't be able to leave the code part.
 /// `line_suffix_boundary` is an explicit marker you can use to flush the `line_suffix` buffer in addition to line breaks.
 /// <https://github.com/prettier/prettier/blob/3.4.2/commands.md#linesuffixboundary>
@@ -316,6 +329,8 @@ macro_rules! indent {
     }};
 }
 
+/// `indent_if_break`
+///
 /// An optimized version of `if_break(indent(doc), doc, group_id)`.
 /// It doesn't make sense to apply `indent_if_break` to the current group,
 /// because "indent if the current group is broken" is the normal behavior of indent.

crates/oxc_span/src/cmp.rs

@@ -1,8 +1,9 @@
 //! Specialized comparison traits
 
 /// This trait works similarly to [PartialEq] but it gives the liberty of checking the equality of the
-/// content loosely. This would mean the implementor can skip some parts of the content while doing
-/// equality checks.
+/// content loosely.
+///
+/// This would mean the implementor can skip some parts of the content while doing equality checks.
 /// As an example, In AST types we ignore fields such as [crate::Span].
 ///
 /// One should always prefer using the [PartialEq] over this since implementations of this trait

tasks/website/src/linter/rules/mod.rs

@@ -27,6 +27,8 @@ Arguments:
 
 ";
 
+/// `print_rules`
+///
 /// `cargo run -p website linter-rules --table
 /// /path/to/oxc/oxc-project.github.io/src/docs/guide/usage/linter/generated-rules.md
 /// --rule-docs /path/to/oxc/oxc-project.github.io/src/docs/guide/usage/linter/rules