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

[GuillaumeGomez]

Implemented in #51140.

[jyn514]

Does this actually need to be stabilized? Even #[no_core] isn't stable and doc(keyword) is pretty useless unless you're core.

[GuillaumeGomez]

It could be very useful for proc-macros. :)

[jyn514]

cc @danielhenrymantilla - do you know if this works/is useful for proc-macros?

[danielhenrymantilla]

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:

1. 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".

[GuillaumeGomez]

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 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?

[GuillaumeGomez]

@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]

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.

[GuillaumeGomez]

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]

@pickfire

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:

https://github.com/GuillaumeGomez/rust/blob/2f7fa24aee7f7e69f9fbc37e8d2084fb1c898e97/src/librustdoc/clean/mod.rs#L309-L316

[GuillaumeGomez]

@danielhenrymantilla Completely forgot about that one... Good catch, thanks a lot!

[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:

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]

I think it should allow all keywords. The goal being to be able to document macro specific keywords in the end...