Using macro to generate generic docs?

We were recently able to finally make the docs for integer primitive types much more accurate (thanks to @antoyo!). Now, the code examples match the type for which they're written. No more i32 examples for i128 (I think you got the idea at this point)!

Now, I think a few people might be interested by the method we used to achieve such a result so let's talk about it.

The not very well known #[doc] attribute

All this was possible thanks to this attribute. Since it's not very well-known, let's explain a bit first how this attribute works:

In Rust, you have two ways to add a doc comment over an item:

Run /// The classic one. /// /// Fancy and everything. fn some_function() {}

And the second one is:

Run #[doc = "The not so classic. But works just as fine!"] fn some_function() {}

Now why is not possible to generate generic documentation using "///"?

Macro limitations

I invite you to test this (or at least try to make it work):

Run macro_rules! doc_comment { ($x:expr, $($tt:tt)*) => { $x $($tt)* }; } struct Foo; impl Foo { doc_comment! { concat!("/// ", "something else", stringify!(u32)), fn foo() {} } } fn main() { }

To the adventurous ones: good luck! For the others, here's the solution with #[doc] :

Run macro_rules! doc_comment { ($x:expr, $($tt:tt)*) => { #[doc = $x] $($tt)* }; } struct Foo; impl Foo { doc_comment! { concat!("something else", stringify!(u32)), fn foo() {} } } fn main() { }

Magical! The advantage of $($tt:tt)* is that it works with basically every kind of items you might want to put:

Run doc_comment! { concat!("something else", stringify!(u32)), #[doc = "why not another doc comment?"] #[inline] fn foo() {} }

Again, it's been possible thanks to @antoyo's huge help!