Hello all,
Macros, especially proc macros, are pretty difficult to understand sometimes, and the source code isn't always intuitive to process what's going on. Something that could make this better is if rustdoc
displays the expanded form of the macro below examples, to give any library users a better idea of what the macro actually does - currently, it's often a bit of sorcery.
My thought is this could be optionally enabled with a flag, which would be very useful for crates that ship macros. As a very simple example, to document something like builtin vec!
:
```expand_macros
let vec = vec![1, 2, 3];
```_
This would show its literal form first (per usual), but there would be a dropdown that contains its full macro expansion:
let vec =
<[_]>::into_vec(#[rustc_box] ::alloc::boxed::Box::new([1, 2, 3]));
Rough GUI example:
An alternative, python-inspired syntax to only expand some lines could be something like:
let vec = vec![1, 2, 3]; # macro_expand!
With macro expansion existing in nightly and crates that contain macros becoming more popular, I feel this may be a good documentation option to help demistify them.