How to document macros from a Rust compiler plugin?

Question

I notice that compiler plugins frequently provide macros that the documentation wont even mention. They're registered and created programmatically rather than being defined in a syntax rustdoc recognizes. Naturally, no documentation can be shown.

I'm looking for a way to get around that, some way of generating documentation for a macro that doesn't exist in the crate at compile time.

I notice the syntax crate could benefit from such a thing as well. quote_item, for instance, is completely undocumented. I can't even find the code that registers it.

Answer 1

One possibility is to do what the compiler does: create an empty macro_rules! macro and attach documentation to that. E.g. if a crate defines foo that takes a single expression, then write something like

/// Documentation
#[macro_export]
macro_rules! foo {
     ($e: expr) => ({ /* syntax extension */ })
}

I notice the syntax crate could benefit from such a thing as well. quote_item, for instance, is completely undocumented. I can't even find the code that registers it.

You can search the Rust source for quote_item, which is helpful for two reasons: it gives some examples, and also allows you to track down the definition. The latter is easier using Rust's DXR instance which can search for things with quotes (i.e. can find strings), and includes various source code navigation tricks (like jump-to-definition).