Including doc comments in named! macro (Not complete)

[giodamelio]

I am making a bunch of parsers with the named! macro and I want to be able to include doc comments for them so I can make doc tests. I tried putting them directly before the macro but they don't seem to be picked up by the compiler. So I decided to try to modify the named! macro to support them myself. I knew nothing about macros when I started this little experiment, so please be gentle. Hopefully there is a simple solution that I missed.

After a bit of research I found out that doc comments are actually converted to attributes during compilation, so /// This is a doc comment becomes #[doc = "This is a doc comment"]. Since we can match meta attributes in macros, it should be possible to grab them and stick them before the output function. It seems to work with a simple example(running cargo rustc --lib -- -Z unstable-options --pretty=expanded shows the #[doc] attributes directly above the print function). Unfortunately when I tried to modify the named! macro(with the changes in the commit in this pull request) to do the same thing, I ran info some ambiguity issues that are a bit above my skill level.

error: local ambiguity: multiple parsing options: built-in NTs ident ('name') or 1 other option.

I found an issue about this exact problem, and it does have a work-around, but it seems like a hack, and I don't really understand it enough to try it. Plus I think it would require some pretty big changes to the implementation of the named! macro, which might not be such a good idea.

I am wondering what your thoughts on this are @Geal? Is it even good idea at all. Is the solution worth the changes?

[Geal]

this is definitely useful, but the parsing issue is worrying. I'd prefer a duplication of the named! definitions to make sure they don't collide, and maybe a token separating the docs and the function name.

[keeperofdakeys]

For now, it is much easier to create a second macro that allows adding arbitrary attributes. The only way I could make rustc happy with putting them in named! was adding some kind of prefix for the attribute variants, however the attribute needs to be directly attached to the generated fn. So adding a second macro seems far easier.

I've made the required changes here, let me know if you'd like me to make a pull request.

Edit: Also I totally wanted this feature the first time I used named!.

[keeperofdakeys]

One idea I've come up with is to add this to the top of the named! macro. Then no one will be required to use named_attr directly.

    (#$($args:tt)*) => (
        named_attr!(#$($args)*);
    );

[keeperofdakeys]

I've updated my branch with the addition to named!, which seems like a positive change. So named_attr! is still exported, but named! can be used with or without attributes.

[giodamelio]

@keeperofdakeys Thanks for picking this up. This is all a bit above my skill level as far as macros go. I am going to close this and you can make a new pull.

[keeperofdakeys]

@giodamelio No worries, thanks for doing the initial work - I didn't actually know how to use macro_rules with attributes before this.