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

**URL:** <https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133>\
**Category:** documentation\
**Created:** [August 4, 2022, 11:24pm UTC](https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133 "2022-08-04T23:24:00Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![tgross35](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/tgross35/32/9550_2.png) [@tgross35](https://internals.rust-lang.org/u/tgross35)\
**Post date:** [August 4, 2022, 11:24pm UTC](https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133/1 "2022-08-04T23:24:00Z")

</div>

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!`:

````rust
```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:

```rust
let vec =
        <[_]>::into_vec(#[rustc_box] ::alloc::boxed::Box::new([1, 2, 3]));

```

Rough GUI example:

 ![image](https://us1.discourse-cdn.com/flex002/uploads/rustlang/original/2X/f/f5d908ef6518ffe1fc057f5cc277dbef2dde136b.png)

An alternative, python-inspired syntax to only expand some lines could be something like:

```rust
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.

---

<div class="post-metadata">

**Author:** ![jjpe](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jjpe/32/9779_2.png) [@jjpe](https://internals.rust-lang.org/u/jjpe)\
**Post date:** [August 5, 2022, 10:03pm UTC](https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133/2 "2022-08-05T22:03:31Z")

</div>

> [@tgross35](#):
>
> Macros, especially proc macros, are pretty difficult to understand sometimes

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](https://github.com/dtolnay/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.

---

<div class="post-metadata">

**Author:** ![nacaclanga](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nacaclanga/32/7461_2.png) [@nacaclanga](https://internals.rust-lang.org/u/nacaclanga)\
**Post date:** [August 9, 2022, 4:52pm UTC](https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133/3 "2022-08-09T16:52:53Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\
**Post date:** [November 7, 2022, 4:53pm UTC](https://internals.rust-lang.org/t/rustdoc-suggestion-optionally-show-macro-expansions-within-a-dropdown/17133/4 "2022-11-07T16:53:20Z")

</div>

Closed on November 7, 2022, 4:53pm UTC

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.
