Macros: documentation and visiblity


#1

I’ve been playing around with nom/macros a little and I noticed something that puzzles me.
Crates using nom make use of the named! macro, which generates a function. The problem is that documenting these generated functions seems to not be possible. Am I wrong? It is code that generates code, you can put a comment above the use of the macro, but that will just not show up in the documentation.

A second thing I noticed was that nom declares a number of macros which it names ..._parser and documents them with “Do not use directly”. This points to the problem that macros don’t have the concept of visibility. They can not be public or private. Right?
And removed the export_macro attribute breaks things.

Is there already a discussion on these things?


#2

For the first issue, the way macro expansion works here is a little tricky… you actually have to pass the doc-comment in as part of the macro. Something like this:

macro_rules! f { ($(#[$attr:meta])*) => { $(#[$attr])* fn xxxxx() {} } }
f!(
    /// Test doc comment
);

For the second issue, not sure if it’s been discussed.