Document meaning of nonterminals via comments?!

[lukaslueg]

There is currently no way in Rust itself to have per-nonterminal documentation. For example, in nom4::method, there is just no way to express what a, _self and args actually do.

One could come up with a convention to document this in a standardized way that does not hurt rustdoc, rustc or readability but can be parsed and use as tooltips, legend or something else in these diagrams.

Cooked up example:

/// This is the panic-macro. It causes panic.
///
/// $msg:expr Something that evaluates to a string, may be printed to stderr if possible
/// $fmt::expr A format string, as used `::std::fmt`
/// $arg::tt Arguments to the format string
macro_rules! panic {
    () => { ... };
    ($msg:expr) => { ... };
    ($msg:expr,) => { ... };
    ($fmt:expr, $($arg:tt)+) => { ... };
}

We could associate that comment, parse the mini-language and use the hints as further explanation. Note that each name:fragment can only appear once, as macro_railroads already implies that a name:fragment-tuple carries the same meaning throughout the macro definition.