feat: Add documentation for lint groups

crates/xtask-lint-docs/src/main.rs

@@ -41,6 +41,8 @@ fn main() -> anyhow::Result<()> {
     )?;
     writeln!(buf)?;
 
+    lint_groups(&mut buf)?;
+
     if !allow.is_empty() {
         add_level_section(LintLevel::Allow, &allow, &mut buf)?;
     }
@@ -69,13 +71,51 @@ fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-fn add_lint(lint: &Lint, buf: &mut String) -> std::fmt::Result {
-    writeln!(buf, "## `{}`", lint.name)?;
+fn lint_groups(buf: &mut String) -> anyhow::Result<()> {
+    let (max_name_len, max_desc_len) = cargo::lints::LINT_GROUPS.iter().filter(|g| !g.hidden).fold(
+        (0, 0),
+        |(max_name_len, max_desc_len), group| {
+            // We add 9 to account for the "cargo::" prefix and backticks
+            let name_len = group.name.chars().count() + 9;
+            let desc_len = group.desc.chars().count();
+            (max_name_len.max(name_len), max_desc_len.max(desc_len))
+        },
+    );
+    let default_level_len = "Default level".chars().count();
+    writeln!(buf, "\n")?;
     writeln!(
         buf,
-        "Set to `{}` by default",
-        lint.primary_group.default_level
+        "| {:<max_name_len$} | {:<max_desc_len$} | Default level |",
+        "Group", "Description",
     )?;
+    writeln!(
+        buf,
+        "|-{}-|-{}-|-{}-|",
+        "-".repeat(max_name_len),
+        "-".repeat(max_desc_len),
+        "-".repeat(default_level_len)
+    )?;
+    for group in cargo::lints::LINT_GROUPS.iter() {
+        if group.hidden {
+            continue;
+        }
+        let group_name = format!("`cargo::{}`", group.name);
+        writeln!(
+            buf,
+            "| {:<max_name_len$} | {:<max_desc_len$} | {:<default_level_len$} |",
+            group_name,
+            group.desc,
+            group.default_level.to_string(),
+        )?;
+    }
+    writeln!(buf, "\n")?;
+    Ok(())
+}
+
+fn add_lint(lint: &Lint, buf: &mut String) -> std::fmt::Result {
+    writeln!(buf, "## `{}`", lint.name)?;
+    writeln!(buf, "Group: `{}`\n", lint.primary_group.name)?;
+    writeln!(buf, "Level: `{}`", lint.primary_group.default_level)?;
     writeln!(buf, "{}\n", lint.docs.as_ref().unwrap())
 }
 

src/cargo/lints/mod.rs

@@ -17,7 +17,7 @@ use std::path::Path;
 pub mod rules;
 pub use rules::LINTS;
 
-const LINT_GROUPS: &[LintGroup] = &[
+pub const LINT_GROUPS: &[LintGroup] = &[
     COMPLEXITY,
     CORRECTNESS,
     NURSERY,
@@ -269,6 +269,7 @@ pub struct LintGroup {
     pub default_level: LintLevel,
     pub desc: &'static str,
     pub feature_gate: Option<&'static Feature>,
+    pub hidden: bool,
 }
 
 const COMPLEXITY: LintGroup = LintGroup {
@@ -276,6 +277,7 @@ const COMPLEXITY: LintGroup = LintGroup {
     desc: "code that does something simple but in a complex way",
     default_level: LintLevel::Warn,
     feature_gate: None,
+    hidden: false,
 };
 
 const CORRECTNESS: LintGroup = LintGroup {
@@ -283,6 +285,7 @@ const CORRECTNESS: LintGroup = LintGroup {
     desc: "code that is outright wrong or useless",
     default_level: LintLevel::Deny,
     feature_gate: None,
+    hidden: false,
 };
 
 const NURSERY: LintGroup = LintGroup {
@@ -290,6 +293,7 @@ const NURSERY: LintGroup = LintGroup {
     desc: "new lints that are still under development",
     default_level: LintLevel::Allow,
     feature_gate: None,
+    hidden: false,
 };
 
 const PEDANTIC: LintGroup = LintGroup {
@@ -297,6 +301,7 @@ const PEDANTIC: LintGroup = LintGroup {
     desc: "lints which are rather strict or have occasional false positives",
     default_level: LintLevel::Allow,
     feature_gate: None,
+    hidden: false,
 };
 
 const PERF: LintGroup = LintGroup {
@@ -304,6 +309,7 @@ const PERF: LintGroup = LintGroup {
     desc: "code that can be written to run faster",
     default_level: LintLevel::Warn,
     feature_gate: None,
+    hidden: false,
 };
 
 const RESTRICTION: LintGroup = LintGroup {
@@ -311,6 +317,7 @@ const RESTRICTION: LintGroup = LintGroup {
     desc: "lints which prevent the use of Cargo features",
     default_level: LintLevel::Allow,
     feature_gate: None,
+    hidden: false,
 };
 
 const STYLE: LintGroup = LintGroup {
@@ -318,6 +325,7 @@ const STYLE: LintGroup = LintGroup {
     desc: "code that should be written in a more idiomatic way",
     default_level: LintLevel::Warn,
     feature_gate: None,
+    hidden: false,
 };
 
 const SUSPICIOUS: LintGroup = LintGroup {
@@ -325,6 +333,7 @@ const SUSPICIOUS: LintGroup = LintGroup {
     desc: "code that is most likely wrong or useless",
     default_level: LintLevel::Warn,
     feature_gate: None,
+    hidden: false,
 };
 
 /// This lint group is only to be used for testing purposes
@@ -333,6 +342,7 @@ const TEST_DUMMY_UNSTABLE: LintGroup = LintGroup {
     desc: "test_dummy_unstable is meant to only be used in tests",
     default_level: LintLevel::Allow,
     feature_gate: Some(Feature::test_dummy_unstable()),
+    hidden: true,
 };
 
 #[derive(Copy, Clone, Debug)]

src/doc/src/reference/lints.md

@@ -2,6 +2,20 @@
 
 Note: [Cargo's linting system is unstable](unstable.md#lintscargo) and can only be used on nightly toolchains
 
+
+
+| Group                | Description                                                      | Default level |
+|----------------------|------------------------------------------------------------------|---------------|
+| `cargo::complexity`  | code that does something simple but in a complex way             | warn          |
+| `cargo::correctness` | code that is outright wrong or useless                           | deny          |
+| `cargo::nursery`     | new lints that are still under development                       | allow         |
+| `cargo::pedantic`    | lints which are rather strict or have occasional false positives | allow         |
+| `cargo::perf`        | code that can be written to run faster                           | warn          |
+| `cargo::restriction` | lints which prevent the use of Cargo features                    | allow         |
+| `cargo::style`       | code that should be written in a more idiomatic way              | warn          |
+| `cargo::suspicious`  | code that is most likely wrong or useless                        | warn          |
+
+
 ## Allowed-by-default
 
 These lints are all set to the 'allow' level by default.
@@ -14,7 +28,9 @@ These lints are all set to the 'warn' level by default.
 - [`unknown_lints`](#unknown_lints)
 
 ## `blanket_hint_mostly_unused`
-Set to `warn` by default
+Group: `suspicious`
+
+Level: `warn`
 
 ### What it does
 Checks if `hint-mostly-unused` being applied to all dependencies.
@@ -42,7 +58,9 @@ hint-mostly-unused = true
 
 
 ## `implicit_minimum_version_req`
-Set to `allow` by default
+Group: `pedantic`
+
+Level: `allow`
 
 ### What it does
 
@@ -91,7 +109,9 @@ serde = "1.0.219"
 
 
 ## `unknown_lints`
-Set to `warn` by default
+Group: `suspicious`
+
+Level: `warn`
 
 ### What it does
 Checks for unknown lints in the `[lints.cargo]` table