rustdoc: should we stop showing `#[lang = ...]` and some other attributes?

[Manishearth]

It seems like we should not be showing #[lang = ...] (etc) attributes in rustdoc. Perhaps we should allowlist or denylist such attributes?

cc @rust-lang/rustdoc

[Manishearth]

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, ...)

cc @jsha

[jsha]

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

	const ALLOWED_ATTRIBUTES: &[Symbol] = &[
	sym::export_name,
	sym::lang,
	sym::link_section,
	sym::must_use,
	sym::no_mangle,
	sym::repr,
	sym::non_exhaustive,
	];

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]

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]

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:

[jyn514]

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]

The variants are also duplicated between the declaration and the main docs, but we don't remove the declaration either.

Yeah, I find that duplication a bit annoying :)

[jsha]

@jyn514 said at #83332 (comment):

I think we should fix this by removing the documentation about what #[non_exhaustive] is and linking to the official docs instead: https://doc.rust-lang.org/reference/attributes/type_system.html#the-non_exhaustive-attribute

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]

That would be a bit of inconsistency since the other items in that section would generally be clickable if they showed up elsewhere.

I mean, I think it would also be useful to make items in the declaration clickable.

[camelid]

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.