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]));
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.
You can do what I do: in addition to actually generating that code, before returning the generated code from the macro, also write it to a file e.g. under /tmp/ somewhere. Then I simply open the file in my editor and rustfmt it. I can then read the generated code, nicely formatted and with syntax highlighting. The only thing that doesn't work is symbol resolution, which is logical as by design that code isn't part of any workspace.
I think in the long run, the Rust toolchain should definitely contain a publicly usable macro expander (similar to the recently added rust-analyzer-proc-macro-srv, but usable by tools other them rust-analyzer as well.), that can be called e.g.
