From bd9d3c6176c847f5b114e22d1f92c5f49a5ddd81 Mon Sep 17 00:00:00 2001 From: Nathan Frasier Date: Mon, 7 Aug 2023 21:42:52 -0500 Subject: [PATCH] Doc: add documentation covering usage of the new --cfg flags --- docs/book/src/usage.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/book/src/usage.md b/docs/book/src/usage.md index fdd1e684..ab689a00 100644 --- a/docs/book/src/usage.md +++ b/docs/book/src/usage.md @@ -1,3 +1,29 @@ # Usage This section is intended for users who want to install Marker and run provided lints. + +## Controlling Marker Lints +Once your crate is configured to run some lints, it quickly becomes important to control the lint levels within your +code. Marker provides the ability to use normal lint control attributes like `#[allow(...)]` `#[deny(...)]` and others +to control the behavior of marker lints. + +### On nightly +Marker provides this functionality via the `#[register_tool()]` attribute currently available in +[nightly](https://github.com/rust-lang/rust/issues/66079). If your crate is compiled using nightly, then controlling +lints is as simple as placing `#![feature(register_tool)]` and `#![register_tool(marker)]` at the top of your crate +`lib.rs` or `mod.rs` file. You can then use all of the normal lint attributes you might usually use, on marker provided +lints, like `#[allow(marker::my_lint)]`. + +### On Stable +If your project isn't on nightly, you can still use the `register_tool` attribute, you'll just need to add some extra +guards around it. Marker provides config arguments to rust during the lint passes, so that your linted code can +conditionally apply attributes only during the marker run. + +Specifically marker passes `--cfg=marker` and a `--cfg=marker="my_crate"` flag for each lint crate. This means that you +can use `#[cfg_attr(marker, foo)]` to conditionally apply the `foo` attribute only during lint runs. This can be used +to leverage the fact that lints run using nightly, without requiring the linted crate to compile using nightly. To do +this, add a `#![cfg_attr(marker, feature(register_tool))]` and `#![cfg_attr(marker, register_tool(marker))]` attributes +to the top of your crate file, then you can apply lint level attributes like `#[cfg_attr(marker, allow(marker::foo))]` +to control your marker lints. Additionally, if there are attributes you only want active when marker is aware of +certain lint crates, you can conditionally apply your attribute with something like +`#[cfg_attr(marker = "my_crate", allow(marker::foo))]`.