From 3414824197de54050977b947ef6904e9e213ba13 Mon Sep 17 00:00:00 2001 From: Boshen <1430279+Boshen@users.noreply.github.com> Date: Wed, 19 Feb 2025 15:58:28 +0000 Subject: [PATCH] docs(oxc): enable `clippy::too_long_first_doc_paragraph` (#9237) --- Cargo.toml | 1 + crates/oxc_allocator/src/convert.rs | 7 ++++--- .../src/constant_evaluation/is_literal_value.rs | 4 +++- crates/oxc_linter/src/config/rules.rs | 4 +++- crates/oxc_linter/src/context/mod.rs | 7 ++++--- crates/oxc_macros/src/lib.rs | 7 ++++--- crates/oxc_parser/src/lexer/mod.rs | 1 + crates/oxc_prettier/src/macros.rs | 15 +++++++++++++++ crates/oxc_span/src/cmp.rs | 5 +++-- tasks/website/src/linter/rules/mod.rs | 2 ++ 10 files changed, 40 insertions(+), 13 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f0db99020a02f..1efeaf391b1d7 100644 --- a/Cargo.toml +++ b/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" diff --git a/crates/oxc_allocator/src/convert.rs b/crates/oxc_allocator/src/convert.rs index ce9c30492530f..fcb570e3cdbd6 100644 --- a/crates/oxc_allocator/src/convert.rs +++ b/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; diff --git a/crates/oxc_ecmascript/src/constant_evaluation/is_literal_value.rs b/crates/oxc_ecmascript/src/constant_evaluation/is_literal_value.rs index 22317a7100249..e4deafcd057a0 100644 --- a/crates/oxc_ecmascript/src/constant_evaluation/is_literal_value.rs +++ b/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. /// diff --git a/crates/oxc_linter/src/config/rules.rs b/crates/oxc_linter/src/config/rules.rs index f21c0e554aa05..a4b36d951c103 100644 --- a/crates/oxc_linter/src/config/rules.rs +++ b/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)] diff --git a/crates/oxc_linter/src/context/mod.rs b/crates/oxc_linter/src/context/mod.rs index 0cc29b7469e47..76b305b30f35c 100644 --- a/crates/oxc_linter/src/context/mod.rs +++ b/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>, diff --git a/crates/oxc_macros/src/lib.rs b/crates/oxc_macros/src/lib.rs index 0bdca9bc5e819..6c4664cd835f7 100644 --- a/crates/oxc_macros/src/lib.rs +++ b/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 { diff --git a/crates/oxc_parser/src/lexer/mod.rs b/crates/oxc_parser/src/lexer/mod.rs index 2c41a29f780e9..30a3e966d3cb9 100644 --- a/crates/oxc_parser/src/lexer/mod.rs +++ b/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: /// #[cold] diff --git a/crates/oxc_prettier/src/macros.rs b/crates/oxc_prettier/src/macros.rs index a85ec30c5a095..09aed74e5846d 100644 --- a/crates/oxc_prettier/src/macros.rs +++ b/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. /// @@ -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. /// @@ -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. diff --git a/crates/oxc_span/src/cmp.rs b/crates/oxc_span/src/cmp.rs index 946d24a292886..8febfae49a758 100644 --- a/crates/oxc_span/src/cmp.rs +++ b/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 diff --git a/tasks/website/src/linter/rules/mod.rs b/tasks/website/src/linter/rules/mod.rs index a3e5bd495ca5b..eadd118f25976 100644 --- a/tasks/website/src/linter/rules/mod.rs +++ b/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