3

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.

kmdreko
  • 42,554
  • 6
  • 57
  • 106
mako
  • 1,201
  • 14
  • 30

1 Answers1

3

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).

huon
  • 94,605
  • 21
  • 231
  • 225
  • Cool. Troubleshooting Tip: If one defines the empty macros and invokes them in the same crate, that'll invoke the empty macros rather than the ones registered by the compiler plugin, which is the opposite of what you want. Do not be alarmed. Once the empty macros are defined in a separate crate from the invocation site, the procedural macros will be called as expected. – mako Jan 19 '16 at 00:14