Rustdoc suggestion: Optionally show macro expansions (within a dropdown)

documentation
#1

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:

image
image714×213 19.8 KB

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.

6 Likes
#2

As someone who's developed his fair share of macros (both declarative and proc macros), I think the tooling could definitely be improved, yes.

However, today you do have some options:

  1. Use cargo-expand
  2. 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.
#3

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.

rustc-macro-expander procmacrobuild.so < input.json > output.json

Where the json files contain some stable representation of tokenstreams and the .so file contains the previously build proc-macro