The fact that:

#[cfg(any())]
#[doc(keyword = "foo")]
mod foo {}

already compiles fine means that a proc-macro can be put instead of #[cfg(any())] and if it strips the #[doc(keyword = …)] from the emitted code, it will not get into trouble. So if proc-macros wanted to use #[doc(keyword = …)] as extra input to it (I personally find it a bit odd, but I may very well lack the imagination for a motivating use-case 🤷 ), then they currently already can.

lack the imagination

Ok, I have had some enlightenment all of a sudden, and I may know what @GuillaumeGomez meant by that: it would be a way to "document" special keywords a macro may take, either as direct params of a proc_macro_attribute, or as special helper / inert attributes of a #[proc_macro_derive)]:

That can be an actually very nice use case, but, in this case, using the mechanics to document a language keyword for custom proc-macros keywords is a bit hacky, and it does impact the resulting ergonomics of it:

First and foremost, the current implementation of it forbids using any keyword that isn't really one (aside: warning when it's not the case would be a good thing, I was a bit confused when I tried it myself with recursive and nothing was showing up 😅 ; I ended up providing something like unsafe for it to work).
- Documenting the unsafe keyword, however, could be a very interesting thing to do, so as to put the higher-level safety contracts of your crate in that section 🤔

it currently cannot be rendered as a sub-item of the attached proc-macro, so it doesn't "look that nice".

Tracking issue for #[doc(keyword = "...")] #51315

Description

GuillaumeGomezopenedon Jun 2, 2018

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

GuillaumeGomez
openedon Jun 2, 2018