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.
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,_selfandargsactually do.One could come up with a convention to document this in a standardized way that does not hurt
rustdoc,rustcor readability but can be parsed and use as tooltips, legend or something else in these diagrams.Cooked up example:
We could associate that comment, parse the mini-language and use the hints as further explanation. Note that each
name:fragmentcan only appear once, asmacro_railroadsalready implies that aname:fragment-tuple carries the same meaning throughout the macro definition.