patches/syn-2.diff

diff --git a/src/attr.rs b/src/attr.rs
index ff875e1..9b778c8 100644
--- a/src/attr.rs
+++ b/src/attr.rs
@@ -6,6 +6,14 @@ use quote::{quote, quote_spanned, ToTokens};
 use syn::ext::IdentExt as _;
 use syn::parse::{Parse, ParseStream};
 
+/// Arguments to `#[instrument(err(...))]` and `#[instrument(ret(...))]` which describe how the
+/// return value event should be emitted.
+#[derive(Clone, Default, Debug)]
+pub(crate) struct EventArgs {
+    level: Option<Level>,
+    pub(crate) mode: FormatMode,
+}
+
 #[derive(Clone, Default, Debug)]
 pub(crate) struct InstrumentArgs {
     level: Option<Level>,
@@ -14,53 +22,16 @@ pub(crate) struct InstrumentArgs {
     pub(crate) parent: Option<Expr>,
     pub(crate) follows_from: Option<Expr>,
     pub(crate) skips: HashSet<Ident>,
-    pub(crate) skip_all: bool,
     pub(crate) fields: Option<Fields>,
-    pub(crate) err_mode: Option<FormatMode>,
-    pub(crate) ret_mode: Option<FormatMode>,
+    pub(crate) err_args: Option<EventArgs>,
+    pub(crate) ret_args: Option<EventArgs>,
     /// Errors describing any unrecognized parse inputs that we skipped.
     parse_warnings: Vec<syn::Error>,
 }
 
 impl InstrumentArgs {
-    pub(crate) fn level(&self) -> impl ToTokens {
-        fn is_level(lit: &LitInt, expected: u64) -> bool {
-            match lit.base10_parse::<u64>() {
-                Ok(value) => value == expected,
-                Err(_) => false,
-            }
-        }
-
-        match &self.level {
-            Some(Level::Str(ref lit)) if lit.value().eq_ignore_ascii_case("trace") => {
-                quote!(tracing::Level::TRACE)
-            }
-            Some(Level::Str(ref lit)) if lit.value().eq_ignore_ascii_case("debug") => {
-                quote!(tracing::Level::DEBUG)
-            }
-            Some(Level::Str(ref lit)) if lit.value().eq_ignore_ascii_case("info") => {
-                quote!(tracing::Level::INFO)
-            }
-            Some(Level::Str(ref lit)) if lit.value().eq_ignore_ascii_case("warn") => {
-                quote!(tracing::Level::WARN)
-            }
-            Some(Level::Str(ref lit)) if lit.value().eq_ignore_ascii_case("error") => {
-                quote!(tracing::Level::ERROR)
-            }
-            Some(Level::Int(ref lit)) if is_level(lit, 1) => quote!(tracing::Level::TRACE),
-            Some(Level::Int(ref lit)) if is_level(lit, 2) => quote!(tracing::Level::DEBUG),
-            Some(Level::Int(ref lit)) if is_level(lit, 3) => quote!(tracing::Level::INFO),
-            Some(Level::Int(ref lit)) if is_level(lit, 4) => quote!(tracing::Level::WARN),
-            Some(Level::Int(ref lit)) if is_level(lit, 5) => quote!(tracing::Level::ERROR),
-            Some(Level::Path(ref pat)) => quote!(#pat),
-            Some(_) => quote! {
-                compile_error!(
-                    "unknown verbosity level, expected one of \"trace\", \
-                     \"debug\", \"info\", \"warn\", or \"error\", or a number 1-5"
-                )
-            },
-            None => quote!(tracing::Level::INFO),
-        }
+    pub(crate) fn level(&self) -> Level {
+        self.level.clone().unwrap_or(Level::Info)
     }
 
     pub(crate) fn target(&self) -> impl ToTokens {
@@ -146,20 +117,8 @@ impl Parse for InstrumentArgs {
                 if !args.skips.is_empty() {
                     return Err(input.error("expected only a single `skip` argument"));
                 }
-                if args.skip_all {
-                    return Err(input.error("expected either `skip` or `skip_all` argument"));
-                }
                 let Skips(skips) = input.parse()?;
                 args.skips = skips;
-            } else if lookahead.peek(kw::skip_all) {
-                if args.skip_all {
-                    return Err(input.error("expected only a single `skip_all` argument"));
-                }
-                if !args.skips.is_empty() {
-                    return Err(input.error("expected either `skip` or `skip_all` argument"));
-                }
-                let _ = input.parse::<kw::skip_all>()?;
-                args.skip_all = true;
             } else if lookahead.peek(kw::fields) {
                 if args.fields.is_some() {
                     return Err(input.error("expected only a single `fields` argument"));
@@ -167,12 +126,12 @@ impl Parse for InstrumentArgs {
                 args.fields = Some(input.parse()?);
             } else if lookahead.peek(kw::err) {
                 let _ = input.parse::<kw::err>();
-                let mode = FormatMode::parse(input)?;
-                args.err_mode = Some(mode);
+                let err_args = EventArgs::parse(input)?;
+                args.err_args = Some(err_args);
             } else if lookahead.peek(kw::ret) {
                 let _ = input.parse::<kw::ret>()?;
-                let mode = FormatMode::parse(input)?;
-                args.ret_mode = Some(mode);
+                let ret_args = EventArgs::parse(input)?;
+                args.ret_args = Some(ret_args);
             } else if lookahead.peek(Token![,]) {
                 let _ = input.parse::<Token![,]>()?;
             } else {
@@ -190,6 +149,55 @@ impl Parse for InstrumentArgs {
     }
 }
 
+impl EventArgs {
+    pub(crate) fn level(&self, default: Level) -> Level {
+        self.level.clone().unwrap_or(default)
+    }
+}
+
+impl Parse for EventArgs {
+    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
+        if !input.peek(syn::token::Paren) {
+            return Ok(Self::default());
+        }
+        let content;
+        let _ = syn::parenthesized!(content in input);
+        let mut result = Self::default();
+        let mut parse_one_arg =
+            || {
+                let lookahead = content.lookahead1();
+                if lookahead.peek(kw::level) {
+                    if result.level.is_some() {
+                        return Err(content.error("expected only a single `level` argument"));
+                    }
+                    result.level = Some(content.parse()?);
+                } else if result.mode != FormatMode::default() {
+                    return Err(content.error("expected only a single format argument"));
+                } else if let Some(ident) = content.parse::<Option<Ident>>()? {
+                    match ident.to_string().as_str() {
+                        "Debug" => result.mode = FormatMode::Debug,
+                        "Display" => result.mode = FormatMode::Display,
+                        _ => return Err(syn::Error::new(
+                            ident.span(),
+                            "unknown event formatting mode, expected either `Debug` or `Display`",
+                        )),
+                    }
+                }
+                Ok(())
+            };
+        parse_one_arg()?;
+        if !content.is_empty() {
+            if content.lookahead1().peek(Token![,]) {
+                let _ = content.parse::<Token![,]>()?;
+                parse_one_arg()?;
+            } else {
+                return Err(content.error("expected `,` or `)`"));
+            }
+        }
+        Ok(result)
+    }
+}
+
 struct StrArg<T> {
     value: LitStr,
     _p: std::marker::PhantomData<T>,
@@ -224,6 +232,19 @@ impl<T: Parse> Parse for ExprArg<T> {
     }
 }
 
+struct IdentOrSelf(Ident);
+impl Parse for IdentOrSelf {
+    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
+        Ok(Self(
+            if let Ok(self_token) = input.parse::<Token![self]>() {
+                Ident::new("self", self_token.span)
+            } else {
+                input.parse()?
+            },
+        ))
+    }
+}
+
 struct Skips(HashSet<Ident>);
 
 impl Parse for Skips {
@@ -231,16 +252,16 @@ impl Parse for Skips {
         let _ = input.parse::<kw::skip>();
         let content;
         let _ = syn::parenthesized!(content in input);
-        let names: Punctuated<Ident, Token![,]> = content.parse_terminated(Ident::parse_any)?;
+        let names: Punctuated<IdentOrSelf, Token![,]> = Punctuated::parse_terminated(&content)?;
         let mut skips = HashSet::new();
         for name in names {
-            if skips.contains(&name) {
+            if skips.contains(&name.0) {
                 return Err(syn::Error::new(
-                    name.span(),
+                    name.0.span(),
                     "tried to skip the same field twice",
                 ));
             } else {
-                skips.insert(name);
+                skips.insert(name.0);
             }
         }
         Ok(Self(skips))
@@ -260,27 +281,6 @@ impl Default for FormatMode {
     }
 }
 
-impl Parse for FormatMode {
-    fn parse(input: ParseStream<'_>) -> syn::Result<Self> {
-        if !input.peek(syn::token::Paren) {
-            return Ok(FormatMode::default());
-        }
-        let content;
-        let _ = syn::parenthesized!(content in input);
-        let maybe_mode: Option<Ident> = content.parse()?;
-        maybe_mode.map_or(Ok(FormatMode::default()), |ident| {
-            match ident.to_string().as_str() {
-                "Debug" => Ok(FormatMode::Debug),
-                "Display" => Ok(FormatMode::Display),
-                _ => Err(syn::Error::new(
-                    ident.span(),
-                    "unknown error mode, must be Debug or Display",
-                )),
-            }
-        })
-    }
-}
-
 #[derive(Clone, Debug)]
 pub(crate) struct Fields(pub(crate) Punctuated<Field, Token![,]>);
 
@@ -303,7 +303,7 @@ impl Parse for Fields {
         let _ = input.parse::<kw::fields>();
         let content;
         let _ = syn::parenthesized!(content in input);
-        let fields: Punctuated<_, Token![,]> = content.parse_terminated(Field::parse)?;
+        let fields: Punctuated<_, Token![,]> = Punctuated::parse_terminated(&content)?;
         Ok(Self(fields))
     }
 }
@@ -376,9 +376,12 @@ impl ToTokens for FieldKind {
 }
 
 #[derive(Clone, Debug)]
-enum Level {
-    Str(LitStr),
-    Int(LitInt),
+pub(crate) enum Level {
+    Trace,
+    Debug,
+    Info,
+    Warn,
+    Error,
     Path(Path),
 }
 
@@ -388,9 +391,37 @@ impl Parse for Level {
         let _ = input.parse::<Token![=]>()?;
         let lookahead = input.lookahead1();
         if lookahead.peek(LitStr) {
-            Ok(Self::Str(input.parse()?))
+            let str: LitStr = input.parse()?;
+            match str.value() {
+                s if s.eq_ignore_ascii_case("trace") => Ok(Level::Trace),
+                s if s.eq_ignore_ascii_case("debug") => Ok(Level::Debug),
+                s if s.eq_ignore_ascii_case("info") => Ok(Level::Info),
+                s if s.eq_ignore_ascii_case("warn") => Ok(Level::Warn),
+                s if s.eq_ignore_ascii_case("error") => Ok(Level::Error),
+                _ => Err(input.error(
+                    "unknown verbosity level, expected one of \"trace\", \
+                     \"debug\", \"info\", \"warn\", or \"error\", or a number 1-5",
+                )),
+            }
         } else if lookahead.peek(LitInt) {
-            Ok(Self::Int(input.parse()?))
+            fn is_level(lit: &LitInt, expected: u64) -> bool {
+                match lit.base10_parse::<u64>() {
+                    Ok(value) => value == expected,
+                    Err(_) => false,
+                }
+            }
+            let int: LitInt = input.parse()?;
+            match &int {
+                i if is_level(i, 1) => Ok(Level::Trace),
+                i if is_level(i, 2) => Ok(Level::Debug),
+                i if is_level(i, 3) => Ok(Level::Info),
+                i if is_level(i, 4) => Ok(Level::Warn),
+                i if is_level(i, 5) => Ok(Level::Error),
+                _ => Err(input.error(
+                    "unknown verbosity level, expected one of \"trace\", \
+                     \"debug\", \"info\", \"warn\", or \"error\", or a number 1-5",
+                )),
+            }
         } else if lookahead.peek(Ident) {
             Ok(Self::Path(input.parse()?))
         } else {
@@ -399,10 +430,22 @@ impl Parse for Level {
     }
 }
 
+impl ToTokens for Level {
+    fn to_tokens(&self, tokens: &mut TokenStream) {
+        match self {
+            Level::Trace => tokens.extend(quote!(tracing::Level::TRACE)),
+            Level::Debug => tokens.extend(quote!(tracing::Level::DEBUG)),
+            Level::Info => tokens.extend(quote!(tracing::Level::INFO)),
+            Level::Warn => tokens.extend(quote!(tracing::Level::WARN)),
+            Level::Error => tokens.extend(quote!(tracing::Level::ERROR)),
+            Level::Path(ref pat) => tokens.extend(quote!(#pat)),
+        }
+    }
+}
+
 mod kw {
     syn::custom_keyword!(fields);
     syn::custom_keyword!(skip);
-    syn::custom_keyword!(skip_all);
     syn::custom_keyword!(level);
     syn::custom_keyword!(target);
     syn::custom_keyword!(parent);
diff --git a/src/expand.rs b/src/expand.rs
index 7005b44..a4a463a 100644
--- a/src/expand.rs
+++ b/src/expand.rs
@@ -10,7 +10,7 @@ use syn::{
 };
 
 use crate::{
-    attr::{Field, Fields, FormatMode, InstrumentArgs},
+    attr::{Field, Fields, FormatMode, InstrumentArgs, Level},
     MaybeItemFn, MaybeItemFnRef,
 };
 
@@ -64,7 +64,7 @@ pub(crate) fn gen_function<'a, B: ToTokens + 'a>(
     // unreachable, but does affect inference, so it needs to be written
     // exactly that way for it to do its magic.
     let fake_return_edge = quote_spanned! {return_span=>
-        #[allow(unreachable_code, clippy::diverging_sub_expression, clippy::let_unit_value)]
+        #[allow(unreachable_code, clippy::diverging_sub_expression, clippy::let_unit_value, clippy::unreachable)]
         if false {
             let __tracing_attr_fake_return: #return_type =
                 unreachable!("this is just for type inference, and is unreachable code");
@@ -116,7 +116,8 @@ fn gen_block<B: ToTokens>(
         .map(|name| quote!(#name))
         .unwrap_or_else(|| quote!(#instrumented_function_name));
 
-    let level = args.level();
+    let args_level = args.level();
+    let level = args_level.clone();
 
     let follows_from = args.follows_from.iter();
     let follows_from = quote! {
@@ -134,7 +135,7 @@ fn gen_block<B: ToTokens>(
             .into_iter()
             .flat_map(|param| match param {
                 FnArg::Typed(PatType { pat, ty, .. }) => {
-                    param_names(*pat, RecordType::parse_from_ty(&*ty))
+                    param_names(*pat, RecordType::parse_from_ty(&ty))
                 }
                 FnArg::Receiver(_) => Box::new(iter::once((
                     Ident::new("self", param.span()),
@@ -178,7 +179,7 @@ fn gen_block<B: ToTokens>(
         let quoted_fields: Vec<_> = param_names
             .iter()
             .filter(|(param, _)| {
-                if args.skip_all || args.skips.contains(param) {
+                if args.skips.contains(param) {
                     return false;
                 }
 
@@ -232,21 +233,33 @@ fn gen_block<B: ToTokens>(
 
     let target = args.target();
 
-    let err_event = match args.err_mode {
-        Some(FormatMode::Default) | Some(FormatMode::Display) => {
-            Some(quote!(tracing::error!(target: #target, error = %e)))
+    let err_event = match args.err_args {
+        Some(event_args) => {
+            let level_tokens = event_args.level(Level::Error);
+            match event_args.mode {
+                FormatMode::Default | FormatMode::Display => Some(quote!(
+                    tracing::event!(target: #target, #level_tokens, error = %e)
+                )),
+                FormatMode::Debug => Some(quote!(
+                    tracing::event!(target: #target, #level_tokens, error = ?e)
+                )),
+            }
         }
-        Some(FormatMode::Debug) => Some(quote!(tracing::error!(target: #target, error = ?e))),
         _ => None,
     };
 
-    let ret_event = match args.ret_mode {
-        Some(FormatMode::Display) => Some(quote!(
-            tracing::event!(target: #target, #level, return = %x)
-        )),
-        Some(FormatMode::Default) | Some(FormatMode::Debug) => Some(quote!(
-            tracing::event!(target: #target, #level, return = ?x)
-        )),
+    let ret_event = match args.ret_args {
+        Some(event_args) => {
+            let level_tokens = event_args.level(args_level);
+            match event_args.mode {
+                FormatMode::Display => Some(quote!(
+                    tracing::event!(target: #target, #level_tokens, return = %x)
+                )),
+                FormatMode::Default | FormatMode::Debug => Some(quote!(
+                    tracing::event!(target: #target, #level_tokens, return = ?x)
+                )),
+            }
+        }
         _ => None,
     };
 
@@ -464,10 +477,7 @@ fn param_names(pat: Pat, record_type: RecordType) -> Box<dyn Iterator<Item = (Id
                 .into_iter()
                 .flat_map(|p| param_names(p, RecordType::Debug)),
         ),
-        Pat::TupleStruct(PatTupleStruct {
-            pat: PatTuple { elems, .. },
-            ..
-        }) => Box::new(
+        Pat::TupleStruct(PatTupleStruct { elems, .. }) => Box::new(
             elems
                 .into_iter()
                 .flat_map(|p| param_names(p, RecordType::Debug)),
@@ -551,7 +561,7 @@ impl<'block> AsyncInfo<'block> {
         // last expression of the block: it determines the return value of the
         // block, this is quite likely a `Box::pin` statement or an async block
         let (last_expr_stmt, last_expr) = block.stmts.iter().rev().find_map(|stmt| {
-            if let Stmt::Expr(expr) = stmt {
+            if let Stmt::Expr(expr, _) = stmt {
                 Some((stmt, expr))
             } else {
                 None
diff --git a/src/lib.rs b/src/lib.rs
index f5974e4..4b92520 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -12,11 +12,11 @@
 //!
 //! ## Usage
 //!
-//! First, add this to your `Cargo.toml`:
+//! In the `Cargo.toml`:
 //!
 //! ```toml
 //! [dependencies]
-//! tracing-attributes = "0.1.23"
+//! tracing = "0.1"
 //! ```
 //!
 //! The [`#[instrument]`][instrument] attribute can now be added to a function
@@ -24,7 +24,7 @@
 //! called. For example:
 //!
 //! ```
-//! use tracing_attributes::instrument;
+//! use tracing::instrument;
 //!
 //! #[instrument]
 //! pub fn my_function(my_arg: usize) {
@@ -35,8 +35,8 @@
 //! ```
 //!
 //! [`tracing`]: https://crates.io/crates/tracing
+//! [instrument]: macro@instrument
 //! [span]: https://docs.rs/tracing/latest/tracing/span/index.html
-//! [instrument]: macro@self::instrument
 //!
 //! ## Supported Rust Versions
 //!
@@ -52,19 +52,17 @@
 //! supported compiler version is not considered a semver breaking change as
 //! long as doing so complies with this policy.
 //!
-#![doc(html_root_url = "https://docs.rs/tracing-attributes/0.1.23")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
+    html_favicon_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/favicon.ico",
     issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
 )]
-#![cfg_attr(docsrs, deny(rustdoc::broken_intra_doc_links))]
 #![warn(
     missing_debug_implementations,
     missing_docs,
     rust_2018_idioms,
     unreachable_pub,
     bad_style,
-    const_err,
     dead_code,
     improper_ctypes,
     non_shorthand_field_patterns,
@@ -79,12 +77,9 @@
     unused_parens,
     while_true
 )]
-// TODO: once `tracing` bumps its MSRV to 1.42, remove this allow.
-#![allow(unused)]
-extern crate proc_macro;
 
 use proc_macro2::TokenStream;
-use quote::ToTokens;
+use quote::{quote, ToTokens};
 use syn::parse::{Parse, ParseStream};
 use syn::{Attribute, ItemFn, Signature, Visibility};
 
@@ -93,7 +88,7 @@ mod expand;
 /// Instruments a function to create and enter a `tracing` [span] every time
 /// the function is called.
 ///
-/// Unless overriden, a span with the [`INFO`] [level] will be generated.
+/// Unless overriden, a span with `info` level will be generated.
 /// The generated span's name will be the name of the function.
 /// By default, all arguments to the function are included as fields on the
 /// span. Arguments that are `tracing` [primitive types] implementing the
@@ -101,216 +96,27 @@ mod expand;
 /// not implement `Value` will be recorded using [`std::fmt::Debug`].
 ///
 /// [primitive types]: https://docs.rs/tracing/latest/tracing/field/trait.Value.html#foreign-impls
-/// [`Value` trait]: https://docs.rs/tracing/latest/tracing/field/trait.Value.html.
-///
-/// # Overriding Span Attributes
-///
-/// To change the [name] of the generated span, add a `name` argument to the
-/// `#[instrument]` macro, followed by an equals sign and a string literal. For
-/// example:
-///
-/// ```
-/// # use tracing_attributes::instrument;
-///
-/// // The generated span's name will be "my_span" rather than "my_function".
-/// #[instrument(name = "my_span")]
-/// pub fn my_function() {
-///     // ... do something incredibly interesting and important ...
-/// }
-/// ```
-///
-/// To override the [target] of the generated span, add a `target` argument to
-/// the `#[instrument]` macro, followed by an equals sign and a string literal
-/// for the new target. The [module path] is still recorded separately. For
-/// example:
-///
-/// ```
-/// pub mod my_module {
-///     # use tracing_attributes::instrument;
-///     // The generated span's target will be "my_crate::some_special_target",
-///     // rather than "my_crate::my_module".
-///     #[instrument(target = "my_crate::some_special_target")]
-///     pub fn my_function() {
-///         // ... all kinds of neat code in here ...
-///     }
-/// }
-/// ```
-///
-/// Finally, to override the [level] of the generated span, add a `level`
-/// argument, followed by an equals sign and a string literal with the name of
-/// the desired level. Level names are not case sensitive. For example:
-///
-/// ```
-/// # use tracing_attributes::instrument;
-/// // The span's level will be TRACE rather than INFO.
-/// #[instrument(level = "trace")]
-/// pub fn my_function() {
-///     // ... I have written a truly marvelous implementation of this function,
-///     // which this example is too narrow to contain ...
-/// }
-/// ```
-///
-/// # Skipping Fields
-///
-/// To skip recording one or more arguments to a function or method, pass
-/// the argument's name inside the `skip()` argument on the `#[instrument]`
-/// macro. This can be used when an argument to an instrumented function does
-/// not implement [`fmt::Debug`], or to exclude an argument with a verbose or
-/// costly `Debug` implementation. Note that:
+/// [`Value` trait]: https://docs.rs/tracing/latest/tracing/field/trait.Value.html
 ///
+/// To skip recording a function's or method's argument, pass the argument's name
+/// to the `skip` argument on the `#[instrument]` macro. For example,
+/// `skip` can be used when an argument to an instrumented function does
+/// not implement [`fmt::Debug`], or to exclude an argument with a verbose
+/// or costly Debug implementation. Note that:
 /// - multiple argument names can be passed to `skip`.
 /// - arguments passed to `skip` do _not_ need to implement `fmt::Debug`.
 ///
-/// You can also use `skip_all` to skip all arguments.
-///
-/// ## Examples
-///
-/// ```
-/// # use tracing_attributes::instrument;
-/// # use std::collections::HashMap;
-/// // This type doesn't implement `fmt::Debug`!
-/// struct NonDebug;
-///
-/// // `arg` will be recorded, while `non_debug` will not.
-/// #[instrument(skip(non_debug))]
-/// fn my_function(arg: usize, non_debug: NonDebug) {
-///     // ...
-/// }
-///
-/// // These arguments are huge
-/// #[instrument(skip_all)]
-/// fn my_big_data_function(large: Vec<u8>, also_large: HashMap<String, String>) {
-///     // ...
-/// }
-/// ```
-///
-/// Skipping the `self` parameter:
-///
-/// ```
-/// # use tracing_attributes::instrument;
-/// #[derive(Debug)]
-/// struct MyType {
-///    data: Vec<u8>, // Suppose this buffer is often quite long...
-/// }
-///
-/// impl MyType {
-///     // Suppose we don't want to print an entire kilobyte of `data`
-///     // every time this is called...
-///     #[instrument(skip(self))]
-///     pub fn my_method(&mut self, an_interesting_argument: usize) {
-///          // ... do something (hopefully, using all that `data`!)
-///     }
-/// }
-/// ```
-///
-/// # Adding Fields
-///
-/// Additional fields (key-value pairs with arbitrary data) may be added to the
-/// generated span using the `fields` argument on the `#[instrument]` macro. Any
-/// Rust expression can be used as a field value in this manner. These
-/// expressions will be evaluated at the beginning of the function's body, so
-/// arguments to the function may be used in these expressions. Field names may
-/// also be specified *without* values. Doing so will result in an [empty field]
-/// whose value may be recorded later within the function body.
-///
-/// This supports the same [field syntax] as the `span!` and `event!` macros.
+/// Additional fields (key-value pairs with arbitrary data) can be passed to
+/// to the generated span through the `fields` argument on the
+/// `#[instrument]` macro. Strings, integers or boolean literals are accepted values
+/// for each field. The name of the field must be a single valid Rust
+/// identifier, nested (dotted) field names are not supported.
 ///
 /// Note that overlap between the names of fields and (non-skipped) arguments
 /// will result in a compile error.
 ///
-/// ## Examples
-///
-/// Adding a new field based on the value of an argument:
-///
-/// ```
-/// # use tracing_attributes::instrument;
-///
-/// // This will record a field named "i" with the value of `i` *and* a field
-/// // named "next" with the value of `i` + 1.
-/// #[instrument(fields(next = i + 1))]
-/// pub fn my_function(i: usize) {
-///     // ...
-/// }
-/// ```
-///
-/// Recording specific properties of a struct as their own fields:
-///
-/// ```
-/// # mod http {
-/// #   pub struct Error;
-/// #   pub struct Response<B> { pub(super) _b: std::marker::PhantomData<B> }
-/// #   pub struct Request<B> { _b: B }
-/// #   impl<B> std::fmt::Debug for Request<B> {
-/// #       fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-/// #           f.pad("request")
-/// #       }
-/// #   }
-/// #   impl<B> Request<B> {
-/// #       pub fn uri(&self) -> &str { "fake" }
-/// #       pub fn method(&self) -> &str { "GET" }
-/// #   }
-/// # }
-/// # use tracing_attributes::instrument;
-///
-/// // This will record the request's URI and HTTP method as their own separate
-/// // fields.
-/// #[instrument(fields(http.uri = req.uri(), http.method = req.method()))]
-/// pub fn handle_request<B>(req: http::Request<B>) -> http::Response<B> {
-///     // ... handle the request ...
-///     # http::Response { _b: std::marker::PhantomData }
-/// }
-/// ```
-///
-/// This can be used in conjunction with `skip` or `skip_all` to record only
-/// some fields of a struct:
-/// ```
-/// # use tracing_attributes::instrument;
-/// // Remember the struct with the very large `data` field from the earlier
-/// // example? Now it also has a `name`, which we might want to include in
-/// // our span.
-/// #[derive(Debug)]
-/// struct MyType {
-///    name: &'static str,
-///    data: Vec<u8>,
-/// }
-///
-/// impl MyType {
-///     // This will skip the `data` field, but will include `self.name`,
-///     // formatted using `fmt::Display`.
-///     #[instrument(skip(self), fields(self.name = %self.name))]
-///     pub fn my_method(&mut self, an_interesting_argument: usize) {
-///          // ... do something (hopefully, using all that `data`!)
-///     }
-/// }
-/// ```
-///
-/// Adding an empty field to be recorded later:
-///
-/// ```
-/// # use tracing_attributes::instrument;
-///
-/// // This function does a very interesting and important mathematical calculation.
-/// // Suppose we want to record both the inputs to the calculation *and* its result...
-/// #[instrument(fields(result))]
-/// pub fn do_calculation(input_1: usize, input_2: usize) -> usize {
-///     // Rerform the calculation.
-///     let result = input_1 + input_2;
-///
-///     // Record the result as part of the current span.
-///     tracing::Span::current().record("result", &result);
-///
-///     // Now, the result will also be included on this event!
-///     tracing::info!("calculation complete!");
-///
-///     // ... etc ...
-///     # 0
-/// }
-/// ```
-///
 /// # Examples
-///
 /// Instrumenting a function:
-///
 /// ```
 /// # use tracing_attributes::instrument;
 /// #[instrument]
@@ -324,11 +130,15 @@ mod expand;
 /// Setting the level for the generated span:
 /// ```
 /// # use tracing_attributes::instrument;
-/// #[instrument(level = "debug")]
+/// # use tracing::Level;
+/// #[instrument(level = Level::DEBUG)]
 /// pub fn my_function() {
 ///     // ...
 /// }
 /// ```
+/// Levels can be specified either with [`Level`] constants, literal strings
+/// (e.g., `"debug"`, `"info"`) or numerically (1—5, corresponding to [`Level::TRACE`]—[`Level::ERROR`]).
+///
 /// Overriding the generated span's name:
 /// ```
 /// # use tracing_attributes::instrument;
@@ -399,7 +209,7 @@ mod expand;
 /// }
 /// ```
 ///
-/// To add an additional context to the span, pass key-value pairs to `fields`:
+/// To add additional context to the span, pass key-value pairs to `fields`:
 ///
 /// ```
 /// # use tracing_attributes::instrument;
@@ -419,10 +229,21 @@ mod expand;
 ///     42
 /// }
 /// ```
-/// The return value event will have the same level as the span generated by `#[instrument]`.
-/// By default, this will be [`INFO`], but if the level is overridden, the event will be at the same
+/// The level of the return value event defaults to the same level as the span generated by `#[instrument]`.
+/// By default, this will be `TRACE`, but if the span level is overridden, the event will be at the same
 /// level.
 ///
+/// It's also possible to override the level for the `ret` event independently:
+///
+/// ```
+/// # use tracing_attributes::instrument;
+/// # use tracing::Level;
+/// #[instrument(ret(level = Level::WARN))]
+/// fn my_function() -> i32 {
+///     42
+/// }
+/// ```
+///
 /// **Note**:  if the function returns a `Result<T, E>`, `ret` will record returned values if and
 /// only if the function returns [`Result::Ok`].
 ///
@@ -438,8 +259,8 @@ mod expand;
 /// }
 /// ```
 ///
-/// If the function returns a `Result<T, E>` and `E` implements `std::fmt::Display`, you can add
-/// `err` or `err(Display)` to emit error events when the function returns `Err`:
+/// If the function returns a `Result<T, E>` and `E` implements `std::fmt::Display`, adding
+/// `err` or `err(Display)` will emit error events when the function returns `Err`:
 ///
 /// ```
 /// # use tracing_attributes::instrument;
@@ -449,9 +270,22 @@ mod expand;
 /// }
 /// ```
 ///
+/// The level of the error value event defaults to `ERROR`.
+///
+/// Similarly, overriding the level of the `err` event :
+///
+/// ```
+/// # use tracing_attributes::instrument;
+/// # use tracing::Level;
+/// #[instrument(err(level = Level::INFO))]
+/// fn my_function(arg: usize) -> Result<(), std::io::Error> {
+///     Ok(())
+/// }
+/// ```
+///
 /// By default, error values will be recorded using their `std::fmt::Display` implementations.
 /// If an error implements `std::fmt::Debug`, it can be recorded using its `Debug` implementation
-/// instead, by writing `err(Debug)`:
+/// instead by writing `err(Debug)`:
 ///
 /// ```
 /// # use tracing_attributes::instrument;
@@ -510,44 +344,21 @@ mod expand;
 /// }
 /// ```
 ///
-/// Note than on `async-trait` <= 0.1.43, references to the `Self`
-/// type inside the `fields` argument were only allowed when the instrumented
-/// function is a method (i.e., the function receives `self` as an argument).
-/// For example, this *used to not work* because the instrument function
-/// didn't receive `self`:
-/// ```
-/// # use tracing::instrument;
-/// use async_trait::async_trait;
-///
-/// #[async_trait]
-/// pub trait Bar {
-///     async fn bar();
-/// }
-///
-/// #[derive(Debug)]
-/// struct BarImpl(usize);
+/// `const fn` cannot be instrumented, and will result in a compilation failure:
 ///
-/// #[async_trait]
-/// impl Bar for BarImpl {
-///     #[instrument(fields(tmp = std::any::type_name::<Self>()))]
-///     async fn bar() {}
-/// }
+/// ```compile_fail
+/// # use tracing_attributes::instrument;
+/// #[instrument]
+/// const fn my_const_function() {}
 /// ```
-/// Instead, you should manually rewrite any `Self` types as the type for
-/// which you implement the trait: `#[instrument(fields(tmp = std::any::type_name::<Bar>()))]`
-/// (or maybe you can just bump `async-trait`).
 ///
 /// [span]: https://docs.rs/tracing/latest/tracing/span/index.html
-/// [name]: https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.name
-/// [target]: https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.target
-/// [level]: https://docs.rs/tracing/latest/tracing/struct.Level.html
-/// [module path]: https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.module_path
-/// [`INFO`]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.INFO
-/// [empty field]: https://docs.rs/tracing/latest/tracing/field/struct.Empty.html
-/// [field syntax]: https://docs.rs/tracing/latest/tracing/#recording-fields
 /// [`follows_from`]: https://docs.rs/tracing/latest/tracing/struct.Span.html#method.follows_from
 /// [`tracing`]: https://github.com/tokio-rs/tracing
 /// [`fmt::Debug`]: std::fmt::Debug
+/// [`Level`]: https://docs.rs/tracing/latest/tracing/struct.Level.html
+/// [`Level::TRACE`]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.TRACE
+/// [`Level::ERROR`]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.ERROR
 #[proc_macro_attribute]
 pub fn instrument(
     args: proc_macro::TokenStream,
@@ -584,6 +395,13 @@ fn instrument_precise(
     let input = syn::parse::<ItemFn>(item)?;
     let instrumented_function_name = input.sig.ident.to_string();
 
+    if input.sig.constness.is_some() {
+        return Ok(quote! {
+            compile_error!("the `#[instrument]` attribute may not be used with `const fn`s")
+        }
+        .into());
+    }
+
     // check for async_trait-like patterns in the block, and instrument
     // the future instead of the wrapper
     if let Some(async_like) = expand::AsyncInfo::from_fn(&input) {