From 4c379ac5cca91ee37cc70fb8453e51c29803c51d Mon Sep 17 00:00:00 2001
From: Mario Carbajal <mario.e.carbajal@gmail.com>
Date: Thu, 1 Feb 2024 22:59:38 -0300
Subject: [PATCH] Documentation for unused classnames and attribute syntax in
 macro

---
 README.md           | 21 ++++++++++++++++++++-
 stylance/src/lib.rs |  8 +++++---
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 006c736..9d8058f 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,9 @@ Stylance is a library and cli tool for working with scoped CSS in rust.
 
 **Features:**
 
--   Import hashed class names from css files into your rust code as string constants. Trying to use a class name that doesn't exist in the css file becomes an error in rust.
+-   Import hashed class names from css files into your rust code as string constants.
+    - Trying to use a class name that doesn't exist in the css file becomes an error.
+    - Unused class names become warnings.
 -   Bundle your css module files into a single output css file with all the class names transformed to include a hash (by using stylance cli).
 -   Class name hashes are deterministic and based on the relative path between the css file and your crate's manifest dir (where the Cargo.toml resides)
 -   CSS Bundle generation is independent of the rust build process, allowing for blazingly fast iteration when modifying the contents of a css style rule.
@@ -70,6 +72,23 @@ this will transform to:
 
 .my_scoped_class got the module hash attached but .paragraph was left alone while the `:global()` was removed.
 
+### Unused classname warnings
+
+The import style macros will crate constants which, if left unused, will produce warnings.
+
+This is helpful if you don't want to have css classes left unused but you are able to silence this warning by adding `#[allow(dead_code)]` before the module identifier in the macro.
+
+Example:
+```rust
+import_crate_style!(#[allow(dead_code)] my_style, "src/component/card/card.module.scss");
+```
+
+Any attribute is allowed, if you want to deny instead you can do it too:
+
+```rust
+import_crate_style!(#[deny(dead_code)] my_style, "src/component/card/card.module.scss");
+```
+
 ### Nightly feature
 
 If you are using rust nightly you can enable the `nightly` feature to get access to the `import_style!` macro which lets you specify the css module file as relative to the current file.
diff --git a/stylance/src/lib.rs b/stylance/src/lib.rs
index c1e5f25..7e182e7 100644
--- a/stylance/src/lib.rs
+++ b/stylance/src/lib.rs
@@ -122,8 +122,9 @@ pub mod internal {
 ///
 /// ### Syntax
 /// ```rust
-/// import_style!([pub] module_identifier, style_path);
+/// import_style!([#[attribute]] [pub] module_identifier, style_path);
 /// ```
+/// - Optionally prefix attributes that will be added to the generated module. Particularly common is `#[allow(dead_code)]` to silence warnings from unused class names.
 /// - Optionally add pub keyword before `module_identifier` to make the generated module public.
 /// - `module_identifier`: This will be used as the name of the module generated by this macro.
 /// - `style_path`: This should be a string literal with the path to a css file inside your rust
@@ -132,7 +133,7 @@ pub mod internal {
 /// ### Example
 /// ```rust
 /// // style.css is located in the same directory as this rust file.
-/// stylance::import_style!(pub style, "style.css");
+/// stylance::import_style!(#[allow(dead_code)] pub style, "style.css");
 ///
 /// fn use_style() {
 ///     println!("{}", style::header);
@@ -161,8 +162,9 @@ macro_rules! import_style {
 ///
 /// ### Syntax
 /// ```rust
-/// import_crate_style!([pub] module_identifier, style_path);
+/// import_crate_style!([#[attribute]] [pub] module_identifier, style_path);
 /// ```
+/// - Optionally prefix attributes that will be added to the generated module. Particularly common is `#[allow(dead_code)]` to silence warnings from unused class names.
 /// - Optionally add pub keyword before `module_identifier` to make the generated module public.
 /// - `module_identifier`: This will be used as the name of the module generated by this macro.
 /// - `style_path`: This should be a string literal with the path to a css file inside your rust