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
Also perhaps we should truncate must_use to not include the full text
I know we used to hide attributes unconditionally and now we show them unconditionally since it's almost always one attribute so it's not a space saving thing, but there's the additional concern about it being distracting. We can probably allowlist to a set of attributes we care about (must_use, repr, no_mangle, link, ...)
I'm removing lang in #84283, along with a reduction in visual weight for all attributes.
I've tried truncating #[must_use] to not include the full text, but I think actually the best thing is to not show #[must_use] at all. It's an attribute on a lot of functions very commonly used by beginners, and the attribute name is not at all self-explanatory. Also, even without must_use listed in the docs, its message will show up at just the time someone needs it - when it generates a compiler warning. In other words, when you're reading the docs, you don't need to know a function is #[must_use] in order to use it correctly.
Oh! I feel like I've even seen that list before 😄, probably just forgot.
Reducing the visual weight is a great idea, thanks!
must_use is ... well, I still find it useful to know things are tagged as such, but I don't mind removing it from the allowlist, it doesn't impact semantics anywhere close to as much as the others do.
must_use is ... well, I still find it useful to know things are tagged as such, but I don't mind removing it from the allowlist, it doesn't impact semantics anywhere close to as much as the others do.
Yeah, I agree. I wonder if we should also stop showing non_exhaustive? Currently, we say that it's non-exhaustive in addition to showing the attribute:
changed the title [-]rustdoc: should we be allowlisting attributes?[/-][+]rustdoc: should we stop showing `#[lang = ...]` and some other attributes?[/+]on Apr 19, 2021
I think #[non_exhausive] is important to show. The variants are also duplicated between the declaration and the main docs, but we don't remove the declaration either.
I agree that we should link all attributes to their official docs. For #[non_exhaustive], that would make it the only clickable hyperlink in the declaration section. That would be a bit of inconsistency since the other items in that section would generally be clickable if they showed up elsewhere. We would also need to highlight it in some way to indicate that it's clickable, which would make it stand out a lot from the rest of the declaration.
It might be nice to use syntax highlighting for the declaration too. I don't think we'd even have to use the rustc lexer because rustdoc knows that e.g. it's emitting an attribute vs visibility.
Activity
Manishearth commentedon Apr 18, 2021
Also perhaps we should truncate
must_use
to not include the full textI know we used to hide attributes unconditionally and now we show them unconditionally since it's almost always one attribute so it's not a space saving thing, but there's the additional concern about it being distracting. We can probably allowlist to a set of attributes we care about (
must_use
,repr
,no_mangle
,link
, ...)cc @jsha
jsha commentedon Apr 18, 2021
There's already an allow list of attributes, but
#[lang]
is on it:rust/src/librustdoc/html/render/mod.rs
Lines 990 to 998 in b021bee
I'm removing
lang
in #84283, along with a reduction in visual weight for all attributes.I've tried truncating
#[must_use]
to not include the full text, but I think actually the best thing is to not show#[must_use]
at all. It's an attribute on a lot of functions very commonly used by beginners, and the attribute name is not at all self-explanatory. Also, even without must_use listed in the docs, its message will show up at just the time someone needs it - when it generates a compiler warning. In other words, when you're reading the docs, you don't need to know a function is#[must_use]
in order to use it correctly.Manishearth commentedon Apr 18, 2021
Oh! I feel like I've even seen that list before 😄, probably just forgot.
Reducing the visual weight is a great idea, thanks!
must_use
is ... well, I still find it useful to know things are tagged as such, but I don't mind removing it from the allowlist, it doesn't impact semantics anywhere close to as much as the others do.camelid commentedon Apr 19, 2021
Yeah, I agree. I wonder if we should also stop showing
non_exhaustive
? Currently, we say that it's non-exhaustive in addition to showing the attribute:[-]rustdoc: should we be allowlisting attributes?[/-][+]rustdoc: should we stop showing `#[lang = ...]` and some other attributes?[/+]jyn514 commentedon Apr 19, 2021
I think
#[non_exhausive]
is important to show. The variants are also duplicated between the declaration and the main docs, but we don't remove the declaration either.camelid commentedon Apr 19, 2021
Yeah, I find that duplication a bit annoying :)
jsha commentedon Apr 20, 2021
@jyn514 said at #83332 (comment):
I agree that we should link all attributes to their official docs. For
#[non_exhaustive]
, that would make it the only clickable hyperlink in the declaration section. That would be a bit of inconsistency since the other items in that section would generally be clickable if they showed up elsewhere. We would also need to highlight it in some way to indicate that it's clickable, which would make it stand out a lot from the rest of the declaration.jyn514 commentedon Apr 20, 2021
I mean, I think it would also be useful to make items in the declaration clickable.
camelid commentedon Apr 22, 2021
It might be nice to use syntax highlighting for the declaration too. I don't think we'd even have to use the rustc lexer because rustdoc knows that e.g. it's emitting an attribute vs visibility.
10 remaining items