Lint documentation improvements (#147)

This PR:

1. Adds documentation to all public items. (Crate-level docs,
module-level docs, other public items.)
2. Adds the `declare_group! {}` macro to automatically document the name
and default level of lint groups.
<img width="1014" alt="image"
src="https://github.com/user-attachments/assets/e1a78c99-e2f3-41c6-8312-52060f9c05a2">
3. Improves the `declare_bevy_lint! {}` macro to auto-document lint
name, group, and description. (Closes #112.) I unfortunately could only
add this to the `LINT_NAME` static and not the module-level docs, but
it's better than looking through the source code.
<img width="1014" alt="image"
src="https://github.com/user-attachments/assets/ca8f1b88-c899-4617-bcbc-0e6206861a85">
<img width="1014" alt="image"
src="https://github.com/user-attachments/assets/957e7e20-ea99-4c7a-947e-4895cdab7585">
4. ~~Made `bevy::insert_event_resource` a Correctness lint instead of
Suspicious, making it deny-by-default. The only time the lint is a false
positive is within `App::add_event()`, since it must internally call
`init_resource::<Events<T>>()`.~~ Edit: reverted due to
#147 (comment).

bevy_lint/src/callback.rs

@@ -1,6 +1,7 @@
 use rustc_driver::Callbacks;
 use rustc_interface::interface::Config;
 
+/// The `rustc` [`Callbacks`] that register Bevy's lints.
 pub struct BevyLintCallback;
 
 impl Callbacks for BevyLintCallback {

bevy_lint/src/groups.rs

@@ -1,71 +1,123 @@
+//! Lint groups that can be toggled together.
+//!
+//! Each lint is organized within a specific category, such as [`PERFORMANCE`] or [`STYLE`].
+
 use crate::{
     lint::{BevyLint, LintGroup},
     lints::LINTS,
 };
 use rustc_lint::{Level, LintStore};
 
-/// A group of deny-by-default lints that check for outright wrong or useless code.
-///
-/// These lints are carefully picked to be free of false positives. You should avoid
-/// `#[allow(...)]`-ing these lints without a _very_ good reason.
-pub static CORRECTNESS: &LintGroup = &LintGroup {
-    name: "bevy::correctness",
-    level: Level::Deny,
-};
+/// A macro for declaring [`LintGroup`]s that auto-generates a table with the name and default
+/// level in the documentation.
+macro_rules! declare_group {
+    {
+        $(#[$attr:meta])*
+        $vis:vis static $static_name:ident = {
+            name: $group_name:literal,
+            level: $level:expr$(,)?
+        };
+    } => {
+        $(#[$attr])*
+        ///
+        /// <table>
+        ///     <tr>
+        ///         <td>Name</td>
+        #[doc = concat!("        <td><code>", stringify!($group_name), "</code></td>")]
+        ///     </tr>
+        ///     <tr>
+        ///         <td>Default Level</td>
+        #[doc = concat!("        <td><code>", stringify!($level), "</code></td>")]
+        ///     </tr>
+        /// </table>
+        $vis static $static_name: &LintGroup = &LintGroup {
+            name: $group_name,
+            level: $level,
+        };
+    };
+}
 
-/// A group similar to [`CORRECTNESS`] that checks for suspicious or usually wrong code.
-///
-/// The linted code may have been written intentionally, but should probably still be fixed.
-pub static SUSPICIOUS: &LintGroup = &LintGroup {
-    name: "bevy::suspicious",
-    level: Level::Warn,
-};
+declare_group! {
+    /// A group of deny-by-default lints that check for outright wrong or useless code.
+    ///
+    /// These lints are carefully picked to be free of false positives. You should avoid
+    /// `#[allow(...)]`-ing these lints without a _very_ good reason.
+    pub static CORRECTNESS = {
+        name: "bevy::correctness",
+        level: Level::Deny,
+    };
+}
 
-/// A group that offers suggestions on how to simplify your code.
-pub static COMPLEXITY: &LintGroup = &LintGroup {
-    name: "bevy::complexity",
-    level: Level::Warn,
-};
+declare_group! {
+    /// A group similar to [`CORRECTNESS`] that checks for suspicious or usually wrong code.
+    ///
+    /// The linted code may have been written intentionally, but should probably still be fixed.
+    pub static SUSPICIOUS = {
+        name: "bevy::suspicious",
+        level: Level::Warn,
+    };
+}
 
-/// A group that suggests how to increase the performance of your code.
-pub static PERFORMANCE: &LintGroup = &LintGroup {
-    name: "bevy::performance",
-    level: Level::Warn,
-};
+declare_group! {
+    /// A group that offers suggestions on how to simplify your code.
+    pub static COMPLEXITY = {
+        name: "bevy::complexity",
+        level: Level::Warn,
+    };
+}
 
-/// A group of lints that encourage idiomatic code.
-///
-/// These lints are opinionated and may be freely disabled if you disagree with their suggestions.
-pub static STYLE: &LintGroup = &LintGroup {
-    name: "bevy::style",
-    level: Level::Warn,
-};
+declare_group! {
+    /// A group that suggests how to increase the performance of your code.
+    pub static PERFORMANCE = {
+        name: "bevy::performance",
+        level: Level::Warn,
+    };
+}
 
-/// A group of lints that make the linter incredibly nit-picky.
-///
-/// If you enable this group, expect to liberally apply `#[allow(...)]` attributes throughout your
-/// code.
-pub static PEDANTIC: &LintGroup = &LintGroup {
-    name: "bevy::pedantic",
-    level: Level::Allow,
-};
+declare_group! {
+    /// A group of lints that encourage idiomatic code.
+    ///
+    /// These lints are opinionated and may be freely disabled if you disagree with their suggestions.
+    pub static STYLE = {
+        name: "bevy::style",
+        level: Level::Warn,
+    };
+}
 
-/// A group of opt-in lints that restrict you from writing certain code.
-///
-/// These are designed for scenarios where you want to increase the consistency of your code-base
-/// and reject certain patterns. They should not all be enabled at once, but instead specific lints
-/// should be individually enabled.
-pub static RESTRICTION: &LintGroup = &LintGroup {
-    name: "bevy::restriction",
-    level: Level::Allow,
-};
+declare_group! {
+    /// A group of lints that make the linter incredibly nit-picky.
+    ///
+    /// If you enable this group, expect to liberally apply `#[allow(...)]` attributes throughout your
+    /// code.
+    pub static PEDANTIC = {
+        name: "bevy::pedantic",
+        level: Level::Allow,
+    };
+}
 
-/// A group of unstable lints that may be removed at any time for any reason.
-pub static NURSERY: &LintGroup = &LintGroup {
-    name: "bevy::nursery",
-    level: Level::Allow,
-};
+declare_group! {
+    /// A group of opt-in lints that restrict you from writing certain code.
+    ///
+    /// These are designed for scenarios where you want to increase the consistency of your code-base
+    /// and reject certain patterns. They should not all be enabled at once, but instead specific lints
+    /// should be individually enabled.
+    pub static RESTRICTION = {
+        name: "bevy::restriction",
+        level: Level::Allow,
+    };
+}
 
+declare_group! {
+    /// A group of unstable lints that may be removed at any time for any reason.
+    pub static NURSERY = {
+        name: "bevy::nursery",
+        level: Level::Allow,
+    };
+}
+
+/// A list of all [`LintGroup`]s.
+///
+/// If a group is not in this list, it will not be registered in [`register_groups()`].
 static GROUPS: &[&LintGroup] = &[
     CORRECTNESS,
     SUSPICIOUS,
@@ -77,6 +129,7 @@ static GROUPS: &[&LintGroup] = &[
     NURSERY,
 ];
 
+/// Registers all [`LintGroup`]s in [`GROUPS`] with the [`LintStore`].
 pub(crate) fn register_groups(store: &mut LintStore) {
     for &group in GROUPS {
         let lints = LINTS

bevy_lint/src/lib.rs

@@ -1,3 +1,8 @@
+//! `bevy_lint` is a Rust linter for the [Bevy game engine](https://bevyengine.org).
+//!
+//! This is the primary documentation for its supported lints and lint groups. It is not intended
+//! to be consumed as a library.
+
 // Enables linking to `rustc` crates.
 #![feature(rustc_private)]
 // Allows chaining `if let` multiple times using `&&`.

bevy_lint/src/lint.rs

@@ -37,6 +37,15 @@ macro_rules! declare_bevy_lint {
         $group:ident,
         $desc:expr$(,)?
     } => {
+        /// Click me for more information.
+        ///
+        /// ```ignore
+        /// Lint {
+        #[doc = concat!("    name: \"bevy::", stringify!($name), "\",")]
+        #[doc = concat!("    group: ", stringify!($group), ",")]
+        #[doc = concat!("    description: ", stringify!($desc), ",")]
+        /// }
+        /// ```
         $(#[$attr])*
         $vis static $name: &$crate::lint::BevyLint = &$crate::lint::BevyLint {
             lint: &::rustc_lint::Lint {

bevy_lint/src/lints/mod.rs

@@ -1,3 +1,7 @@
+//! All lints offered by `bevy_lint`.
+//!
+//! Click on each module to learn more about individual lints.
+
 use crate::lint::BevyLint;
 use rustc_lint::{Lint, LintStore};