Docs. on hover for cfg_attr'

[blyxyas]

Example:

#[doc = include_str!(...)]

The code fragment above will display documentation on hover when the user hovers over doc, and over include_str. Both with their respective documentation.

If the user instead uses #[cfg_attr(doc, doc = include_str!(...))], which reduces compilation time, no documentation will be shown for doc or include_str.

It would be excellent if we could treat the second meta item in the metalist for cfg_attr as it's own attribute (because it is)

[blyxyas]

@rustbot label: +A-hover

[ChayimFriedman2]

I think we do evaluate cfg_attrs here, but we don't set cfg(doc). You can try adding it to rust-analyzer.cargo.cfgs.

[blyxyas]

How do I add it? I've tried setting it to {"doc": true}, {"doc": "true"}, {"doc": {}} and ["doc"] but no hover hints on the attribute appear after a server restart.

[ChayimFriedman2]

Oh we do evaluate cfgs, but even if you set cfg(doc) we don't currently support doc = include_str!(), even when it's not under cfg. I believe there is an issue about that.

[lnicola]

#11137

[lnicola]

I wanted to close this, but we don't support code that's gated for a different platform, so it might actually be a good idea to enable cfg(doc) by default.

[ChayimFriedman2]

I'm not sure we should enable cfg(doc). People use it, e.g. to show documentation even of the non-current platform, and it may cause wrong diagnostics to be emitted if we enable it. IMO we should leave it to users who want it to enable it themselves.

[blyxyas]

There seems to be a misunderstandment:

When I hover over the include_str macro, I get some documentation from std::macros::builtin.
The same, when I hover over doc in #[doc = ...] I get the following:

#[doc]
Valid forms are:

#[doc(hidden|inline|...)]
#[doc = string]

That's what's lost with cfg_attr.

[ChayimFriedman2]

Ah that's indeed a different thing, and it isn't unique to doc, it's the same with all attributes that have hover info.

[GuillaumeGomez]

Enabling cfg(doc) by default doesn't sound like a good idea. In some crates (like std), the items generated for docs are not the actual implementations. Just a trick to give information whatever the platform.

Would it be possible to just expand cfg_attr(doc, doc = ...) in any case?