You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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".
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. :)
@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 ran cargo doc but the keywords section doesn't seemed to be there.
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:
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:
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.
Activity
jyn514 commentedon Nov 4, 2020
Does this actually need to be stabilized? Even
#[no_core]isn't stable anddoc(keyword)is pretty useless unless you'recore.GuillaumeGomez commentedon Nov 4, 2020
It could be very useful for proc-macros. :)
jyn514 commentedon Nov 4, 2020
cc @danielhenrymantilla - do you know if this works/is useful for proc-macros?
danielhenrymantilla commentedon Nov 4, 2020
The fact that:
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.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).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 🤔GuillaumeGomez commentedon Nov 4, 2020
Exactly! Sorry, I should have precised my words. :)
pickfire commentedon Nov 25, 2020
I can't seemed to get this working.
Also, what happens if there is no
mod? Will the doc just silently disappear?GuillaumeGomez commentedon Nov 25, 2020
@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. :)
pickfire commentedon Nov 25, 2020
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.GuillaumeGomez commentedon Nov 25, 2020
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...danielhenrymantilla commentedon Nov 25, 2020
@pickfire
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:https://github.com/GuillaumeGomez/rust/blob/2f7fa24aee7f7e69f9fbc37e8d2084fb1c898e97/src/librustdoc/clean/mod.rs#L309-L316
GuillaumeGomez commentedon Nov 25, 2020
@danielhenrymantilla Completely forgot about that one... Good catch, thanks a lot!
pickfire commentedon Nov 26, 2020
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.
GuillaumeGomez commentedon Nov 26, 2020
I think it should allow all keywords. The goal being to be able to document macro specific keywords in the end...
Rollup merge of rust-lang#79464 - GuillaumeGomez:doc-keyword-ident, r…
Rollup merge of rust-lang#79464 - GuillaumeGomez:doc-keyword-ident, r…
ices/83512.rs: fixed with errors
fmease commentedon Oct 10, 2025
Superseded / subsumed by #90418.