From 349eb67b5b4696d72bde066884b7c3afd2f36e43 Mon Sep 17 00:00:00 2001 From: Oliver Tale-Yazdi Date: Sat, 6 May 2023 10:23:25 +0200 Subject: [PATCH] Add docs and UI tests Signed-off-by: Oliver Tale-Yazdi --- Cargo.toml | 23 ++++----------- README.md | 20 ++++++++++--- proc-macro-warning/Cargo.toml | 21 ++++++++++++++ {src => proc-macro-warning/src}/lib.rs | 24 ++++++++++------ {src => proc-macro-warning/src}/test.rs | 2 +- {tests => ui-tests}/Cargo.toml | 0 {tests => ui-tests}/derive/Cargo.toml | 2 +- {tests => ui-tests}/derive/src/lib.rs | 4 ++- {tests => ui-tests}/ui/Cargo.toml | 0 {tests => ui-tests}/ui/src/lib.rs | 2 ++ .../ui/src/no-warn/derive_no_span.rs | 0 .../ui/src/warn/derive_basic.rs | 5 +--- .../ui/src/warn/derive_basic.stderr | 6 ++-- ui-tests/ui/src/warn/derive_twice_errors.rs | 8 ++++++ .../ui/src/warn/derive_twice_errors.stderr | 28 +++++++++++++++++++ 15 files changed, 105 insertions(+), 40 deletions(-) create mode 100644 proc-macro-warning/Cargo.toml rename {src => proc-macro-warning/src}/lib.rs (89%) rename {src => proc-macro-warning/src}/test.rs (95%) rename {tests => ui-tests}/Cargo.toml (100%) rename {tests => ui-tests}/derive/Cargo.toml (71%) rename {tests => ui-tests}/derive/src/lib.rs (90%) rename {tests => ui-tests}/ui/Cargo.toml (100%) rename {tests => ui-tests}/ui/src/lib.rs (90%) rename {tests => ui-tests}/ui/src/no-warn/derive_no_span.rs (100%) rename {tests => ui-tests}/ui/src/warn/derive_basic.rs (53%) rename {tests => ui-tests}/ui/src/warn/derive_basic.stderr (83%) create mode 100644 ui-tests/ui/src/warn/derive_twice_errors.rs create mode 100644 ui-tests/ui/src/warn/derive_twice_errors.stderr diff --git a/Cargo.toml b/Cargo.toml index a3abc5d..0f69d47 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,18 +1,7 @@ -[package] -name = "proc-macro-warning" -version = "0.3.1" -edition = "2021" -license = "GPL-3.0 OR Apache-2.0" -authors = ["Oliver Tale-Yazdi "] -description = "Emit warnings from inside proc macros." -repository = "/~https://github.com/ggwpez/proc-macro-warning" +[workspace] -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html - -[dependencies] -proc-macro2 = { version = "1.0.56", default-features = false } -quote = { version = "1.0.26", default-features = false } -syn = { version = "2.0.15", default-features = false } - -[features] -default = [] +members = [ + "proc-macro-warning", + "ui-tests/derive", + "ui-tests/ui", +] diff --git a/README.md b/README.md index 690f334..68e3fe1 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,25 @@ let warning = Warning::new_deprecated("my_macro") let tokens = quote::quote!(#warning); ``` -This works in derive-macros, but you **must** put in a span, otherwise it will not show up in the compile output. +This works in derive-macros, but you **must** set a span; otherwise it will not show up in the compile output. + +The difference to a `#[deprecated]` attribute is that it emits the warning either way. For example when creating a custom `Deprecated` derive macro, it will warn without the struct being constructed. + +```rust +#[derive(derive::Deprecated)] +struct Test {} + +fn main() { + // Warning triggers although we never used `Test`. + // Otherwise use a normal `#[deprecated]`. +} +``` ## Used In -Substrate (since [#13798](/~https://github.com/paritytech/substrate/pull/13798)) uses this to emit warnings for its FRAME eDSL on deprecated behaviour. +Substrate uses it to emit warnings for its eDSL (FRAME) on deprecated behaviour. The integration was done in [#13798](/~https://github.com/paritytech/substrate/pull/13798) and shows how to use these warnings in macro expansion. -For example not putting a `call_index` on your functions produces: +The warnings are uniformly formatted and have consistent grammar: ```pre warning: use of deprecated constant `pallet::warnings::ImplicitCallIndex_0::_w`: It is deprecated to use implicit call indices. @@ -58,7 +70,7 @@ warning: use of deprecated constant `pallet::warnings::ImplicitCallIndex_0::_w`: | ``` -Or using a hard-coded weight: +A different one: ```pre warning: use of deprecated constant `pallet::warnings::ConstantWeight_0::_w`: It is deprecated to use hard-coded constant as call weight. diff --git a/proc-macro-warning/Cargo.toml b/proc-macro-warning/Cargo.toml new file mode 100644 index 0000000..961821d --- /dev/null +++ b/proc-macro-warning/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "proc-macro-warning" +version = "0.3.1" +edition = "2021" +license = "GPL-3.0 OR Apache-2.0" +authors = ["Oliver Tale-Yazdi "] +description = "Emit warnings from inside proc macros." +repository = "/~https://github.com/ggwpez/proc-macro-warning" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +proc-macro2 = { version = "1.0.56", default-features = false } +quote = { version = "1.0.26", default-features = false } +syn = { version = "2.0.15", default-features = false } + +[dev-dependencies] +derive = { path = "../ui-tests/derive" } + +[features] +default = [] diff --git a/src/lib.rs b/proc-macro-warning/src/lib.rs similarity index 89% rename from src/lib.rs rename to proc-macro-warning/src/lib.rs index ec2631e..0eed591 100644 --- a/src/lib.rs +++ b/proc-macro-warning/src/lib.rs @@ -3,7 +3,7 @@ * SPDX-License-Identifier: (GPL-3.0 or Apache-2.0) */ -#![doc = include_str!("../README.md")] +#![doc = include_str!("../../README.md")] use core::ops::Deref; use proc_macro2::Span; @@ -20,24 +20,25 @@ pub struct Warning { pub span: Span, } -/// Gradually build a "deprecated" `Warning`. +/// Gradually build a *deprecation* `Warning`. /// /// # Example -/// ``` +/// +/// ```rust /// use proc_macro_warning::Warning; /// /// let warning = Warning::new_deprecated("my_macro") /// .old("my_macro()") /// .new("my_macro::new()") /// .help_link("https:://example.com") +/// // Normally you use the input span, but this is an example: /// .span(proc_macro2::Span::call_site()) /// .build(); /// -/// // Use the warning in a proc macro -/// let tokens = quote::quote!(#warning); +/// let mut warnings = vec![warning]; +/// // When adding more, you will need to build each with `.index`. /// -/// let warnings = vec![warning]; -/// // In a proc macro you would expand them inside a module: +/// // In a proc macro you can expand them in a private module: /// quote::quote! { /// mod warnings { /// #( @@ -180,7 +181,7 @@ impl ToTokens for Warning { let q = quote_spanned!(self.span => /// This function should not be called and only exists to emit a compiler warning. /// - /// It is a No-OP if you want try it anyway ;) + /// It is a No-OP in any case. #[allow(dead_code)] #[allow(non_camel_case_types)] #[allow(non_snake_case)] @@ -194,3 +195,10 @@ impl ToTokens for Warning { q.to_tokens(stream); } } + +impl Warning { + /// Consume self and quote it, according to its span, into a TokenStream. + pub fn into_token_stream(self) -> proc_macro2::TokenStream { + quote::quote! { #self }.into() + } +} diff --git a/src/test.rs b/proc-macro-warning/src/test.rs similarity index 95% rename from src/test.rs rename to proc-macro-warning/src/test.rs index dc7f04d..e7624a7 100644 --- a/src/test.rs +++ b/proc-macro-warning/src/test.rs @@ -22,7 +22,7 @@ fn example_works() { let want_tokens = quote!( /// This function should not be called and only exists to emit a compiler warning. /// - /// It is a No-OP if you want try it anyway ;) + /// It is a No-OP in any case. #[allow(dead_code)] #[allow(non_camel_case_types)] #[allow(non_snake_case)] diff --git a/tests/Cargo.toml b/ui-tests/Cargo.toml similarity index 100% rename from tests/Cargo.toml rename to ui-tests/Cargo.toml diff --git a/tests/derive/Cargo.toml b/ui-tests/derive/Cargo.toml similarity index 71% rename from tests/derive/Cargo.toml rename to ui-tests/derive/Cargo.toml index 1e3a3ce..005f686 100644 --- a/tests/derive/Cargo.toml +++ b/ui-tests/derive/Cargo.toml @@ -8,6 +8,6 @@ publish = false proc-macro = true [dependencies] -proc-macro-warning = { path = "../../" } +proc-macro-warning = { path = "../../proc-macro-warning" } quote = "1.0.26" syn = "2.0.15" diff --git a/tests/derive/src/lib.rs b/ui-tests/derive/src/lib.rs similarity index 90% rename from tests/derive/src/lib.rs rename to ui-tests/derive/src/lib.rs index d980488..2b4b294 100644 --- a/tests/derive/src/lib.rs +++ b/ui-tests/derive/src/lib.rs @@ -1,3 +1,5 @@ +//! TESTING ONLY - DO NOT USE. + use proc_macro::TokenStream; use syn::spanned::Spanned; @@ -22,5 +24,5 @@ fn impl_dep(input: TokenStream, span: bool) -> TokenStream { warning }.build(); - quote::quote!{ #warning }.into() + warning.into_token_stream().into() } diff --git a/tests/ui/Cargo.toml b/ui-tests/ui/Cargo.toml similarity index 100% rename from tests/ui/Cargo.toml rename to ui-tests/ui/Cargo.toml diff --git a/tests/ui/src/lib.rs b/ui-tests/ui/src/lib.rs similarity index 90% rename from tests/ui/src/lib.rs rename to ui-tests/ui/src/lib.rs index dc8b8e9..649a475 100644 --- a/tests/ui/src/lib.rs +++ b/ui-tests/ui/src/lib.rs @@ -1,3 +1,5 @@ +//! TESTING ONLY - DO NOT USE. + #[test] #[cfg(test)] fn ui_warm() { diff --git a/tests/ui/src/no-warn/derive_no_span.rs b/ui-tests/ui/src/no-warn/derive_no_span.rs similarity index 100% rename from tests/ui/src/no-warn/derive_no_span.rs rename to ui-tests/ui/src/no-warn/derive_no_span.rs diff --git a/tests/ui/src/warn/derive_basic.rs b/ui-tests/ui/src/warn/derive_basic.rs similarity index 53% rename from tests/ui/src/warn/derive_basic.rs rename to ui-tests/ui/src/warn/derive_basic.rs index 31f5b3f..b14fcd1 100644 --- a/tests/ui/src/warn/derive_basic.rs +++ b/ui-tests/ui/src/warn/derive_basic.rs @@ -1,8 +1,5 @@ #[derive(derive::Deprecated)] -struct Test { - -} +struct Test; fn main() { - let _ = Test { }; } diff --git a/tests/ui/src/warn/derive_basic.stderr b/ui-tests/ui/src/warn/derive_basic.stderr similarity index 83% rename from tests/ui/src/warn/derive_basic.stderr rename to ui-tests/ui/src/warn/derive_basic.stderr index eaff881..abd9ebb 100644 --- a/tests/ui/src/warn/derive_basic.stderr +++ b/ui-tests/ui/src/warn/derive_basic.stderr @@ -3,9 +3,7 @@ error: use of deprecated constant `test::_w`: Please instead bar. --> src/warn/derive_basic.rs:2:1 | -2 | / struct Test { -3 | | -4 | | } - | |_^ +2 | struct Test; + | ^^^^^^^^^^^^ | = note: `-D deprecated` implied by `-D warnings` diff --git a/ui-tests/ui/src/warn/derive_twice_errors.rs b/ui-tests/ui/src/warn/derive_twice_errors.rs new file mode 100644 index 0000000..aa46688 --- /dev/null +++ b/ui-tests/ui/src/warn/derive_twice_errors.rs @@ -0,0 +1,8 @@ +#[derive(derive::Deprecated)] +struct Test; + +#[derive(derive::Deprecated)] +struct Test2; + +fn main() { +} diff --git a/ui-tests/ui/src/warn/derive_twice_errors.stderr b/ui-tests/ui/src/warn/derive_twice_errors.stderr new file mode 100644 index 0000000..190b49c --- /dev/null +++ b/ui-tests/ui/src/warn/derive_twice_errors.stderr @@ -0,0 +1,28 @@ +error[E0428]: the name `test` is defined multiple times + --> src/warn/derive_twice_errors.rs:5:1 + | +2 | struct Test; + | ------------ previous definition of the value `test` here +... +5 | struct Test2; + | ^^^^^^^^^^^^^ `test` redefined here + | + = note: `test` must be defined only once in the value namespace of this module + +error: use of deprecated constant `test::_w`: + It is deprecated to foo. + Please instead bar. + --> src/warn/derive_twice_errors.rs:2:1 + | +2 | struct Test; + | ^^^^^^^^^^^^ + | + = note: `-D deprecated` implied by `-D warnings` + +error: use of deprecated constant `test::_w`: + It is deprecated to foo. + Please instead bar. + --> src/warn/derive_twice_errors.rs:5:1 + | +5 | struct Test2; + | ^^^^^^^^^^^^^