How to embed Rust macro in the documentation?

Question

I want to use the macro in macro-generated documentation:

macro_rules! impl_foo {
    ($name:ident) => {
        /// Returns a new `$name`.
        fn myfoo() -> $name {

        }
    };
}

However, the variable will not be replaced. I also tried using the attribute #[doc]:

macro_rules! impl_foo {
    ($name:ident) => {
        #[doc = concat!("Returns a new `", $name, "`.")]
        fn myfoo() -> $name {

        }
    };
}

This one can't even parse: unexpected token: 'concat'

Answer 1

As far as I know, the best you can do requires some repetition:

macro_rules! impl_foo {
    ($name:ident, $sname:expr) => {
        #[doc = "Returns a new `"]
        #[doc = $sname]
        #[doc = "`."]
        fn myfoo() -> $name {
            42
        }
    };
}

impl_foo!(u32, "u32");

which is displayed as: