Macro declare_lint

macro_rules! declare_lint {
    ($(#[$attr:meta])* $vis: vis $NAME: ident, $Level: ident, $desc: expr) => { ... };
    ($(#[$attr:meta])* $vis: vis $NAME: ident, $Level: ident, $desc: expr,
     $(@eval_always = $eval_always:literal)?
     $(@feature_gate = $gate:ident;)?
     $(@future_incompatible = FutureIncompatibleInfo {
        reason: $reason:expr,
        $($field:ident : $val:expr),* $(,)*
     }; )?
     $(@edition $lint_edition:ident => $edition_level:ident;)?
     $($v:ident),*) => { ... };
}

Declares a static item of type &'static Lint.

See https://rustc-dev-guide.rust-lang.org/diagnostics.html for documentation and guidelines on writing lints.

The macro call should start with a doc comment explaining the lint which will be embedded in the rustc user documentation book. It should be written in markdown and have a format that looks like this:

/// The `my_lint_name` lint detects [short explanation here].
///
/// ### Example
///
/// ```rust
/// [insert a concise example that triggers the lint]
/// ```
///
/// {{produces}}
///
/// ### Explanation
///
/// This should be a detailed explanation of *why* the lint exists,
/// and also include suggestions on how the user should fix the problem.
/// Try to keep the text simple enough that a beginner can understand,
/// and include links to other documentation for terminology that a
/// beginner may not be familiar with. If this is "allow" by default,
/// it should explain why (are there false positives or other issues?). If
/// this is a future-incompatible lint, it should say so, with text that
/// looks roughly like this:
///
/// This is a [future-incompatible] lint to transition this to a hard
/// error in the future. See [issue #xxxxx] for more details.
///
/// [issue #xxxxx]: https://github.com/rust-lang/rust/issues/xxxxx

The {{produces}} tag will be automatically replaced with the output from the example by the build system. If the lint example is too complex to run as a simple example (for example, it needs an extern crate), mark the code block with ignore and manually replace the {{produces}} line with the expected output in a text code block.

If this is a rustdoc-only lint, then only include a brief introduction with a link with the text [rustdoc book] so that the validator knows that this is for rustdoc only (see BROKEN_INTRA_DOC_LINKS as an example).

Commands to view and test the documentation:

• ./x.py doc --stage=1 src/doc/rustc --open: Builds the rustc book and opens it.
• ./x.py test src/tools/lint-docs: Validates that the lint docs have the correct style, and that the code example actually emits the expected lint.

If you have already built the compiler, and you want to make changes to just the doc comments, then use the --keep-stage=0 flag with the above commands to avoid rebuilding the compiler.