Repository navigation
Tracking issue for #[doc(keyword = "...")] #51315
Description
Activity
Does this actually need to be stabilized? Even
#[no_core]isn't stable anddoc(keyword)is pretty useless unless you'recore.It could be very useful for proc-macros. :)
cc @danielhenrymantilla - do you know if this works/is useful for proc-macros?
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
recursiveand nothing was showing up 😅 ; I ended up providing something likeunsafefor it to work).- Documenting the
unsafekeyword, however, could be a very interesting thing to do, so as to put the higher-level safety contracts of your crate in that section 🤔
- Documenting the
- it currently cannot be rendered as a sub-item of the attached proc-macro, so it doesn't "look that nice".
-
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)]:Exactly! Sorry, I should have precised my words. :)
Reacted by Daniel Henry-MantillaI can't seemed to get this working.
#[doc(keyword = "hello")] /// Hello world mod hello {}
Also, what happens if there is no
mod? Will the doc just silently disappear?@pickfire I didn't understand your comment. The best I can recommend you is to look at how we use it in the std library, maybe that will answer your questions. :)
I did look at how it is used in standard library. The code I show above is in
src/lib.rs(with the feature) and I rancargo docbut the keywords section doesn't seemed to be there.Needless to say it's surprising considering that it works perfectly for the std right? 😆
You maybe just missed something? But normally, you just need to enable the feature and then to add
#[doc(keyword = "...")]on an empty module...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 😅
Have you tried using
#[doc(keyword = "unsafe")], for instance? The current list of valid keywords is hard-coded, and when you provide an extraneous one / one that doesn't belong to that list, it silently ignores / discards the attribute / the directive:Reacted by Ivan Tham@danielhenrymantilla Completely forgot about that one... Good catch, thanks a lot!
Reacted by Daniel Henry-MantillaHave you tried using #[doc(keyword = "unsafe")], for instance? The current list of valid keywords is hard-coded, and when you provide an extraneous one / one that doesn't belong to that list, it silently ignores / discards the attribute / the directive:
Thanks for showing that. I didn't know it uses only hard-coded keywords, maybe rust should give an error when using invalid keywords? At least that won't confuse other users.
I think it should allow all keywords. The goal being to be able to document macro specific keywords in the end...
Reacted by Ivan ThamReacted by Daniel Henry-Mantilla- added a commit that references this issue
on Jun 19, 2021
Implemented in #51140.