Technically speaking, the biggest hurdle to pulling this into
rustdoc proper is swapping
libsyntax. We get plain
TokenStreams for macro definitions, but we don’t keep them for very long - instead we pluck out the
Spans for just the matcher arms, convert them to strings, and discard everything else. To give you the same kind of input we’ll need to also save the TokenStream. (You can see where we grab it for local macros and for re-exported ones.)
Once you have that, we’ll want to make sure it appears on the page correctly. How good is SVG support across browsers? We have our official tiered browser support listing, but unofficially, we try to make sure our docs appear fine on browsers way older than that list. Also on a much smaller note, we’d probably want to make sure the colors switch fine when you switch themes in the docs, meaning we’ll want to make sure the colors use classes defined in the main CSS theme, even if it means updating that CSS to add the relevant classes to the color scheme.
However, i’m a little skittish about adding this to rustdoc. Speaking personally, while i think the diagrams are cute, i have a really hard time actually reading them. The way all the tokens get spaced out, it’s hard for me to follow what each branch is meant to represent. I don’t know how much of that is the fault of the railroad diagram and how much can be tweaked outside of it, but it just feels harder to read than if we managed to clean up and/or syntax-highlight the original
Moreover, i’m not sure how well it would fit into the style of how rustdoc displays things. Part of the design ethos in rustdoc is to format things as if they were Rust code, but macros create this gray area where they can accept literally anything if you write the right matcher for it. So i can see where having something other than the
macro_rules! statement is useful, but i’m not sure the railroad diagrams are the answer. At least, not something to apply to every macro ever.
(I may be more open to adding it if it were behind a CLI flag, or were a kind of
#[doc(railroad)] attribute you could add to macro definitions. This would also help us keep it unstable during the initial integration.)