Skip to content

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

Closed
@Manishearth

Description

@Manishearth
Member

image

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

Activity

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Apr 18, 2021
Manishearth

Manishearth commented on Apr 18, 2021

@Manishearth
MemberAuthor

Also perhaps we should truncate must_use to not include the full text

image

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

jsha commented on Apr 18, 2021

@jsha
Contributor

There's already an allow list of attributes, but #[lang] is on it:

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

Manishearth commented on Apr 18, 2021

@Manishearth
MemberAuthor

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

camelid commented on Apr 19, 2021

@camelid
Member

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:

image

changed the title [-]rustdoc: should we be allowlisting attributes?[/-] [+]rustdoc: should we stop showing `#[lang = ...]` and some other attributes?[/+] on Apr 19, 2021
added
A-attributesArea: Attributes (`#[…]`, `#![…]`)
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
on Apr 19, 2021
jyn514

jyn514 commented on Apr 19, 2021

@jyn514
Member

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

camelid commented on Apr 19, 2021

@camelid
Member

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

jsha commented on Apr 20, 2021

@jsha
Contributor

@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

jyn514 commented on Apr 20, 2021

@jyn514
Member

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

camelid commented on Apr 22, 2021

@camelid
Member

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

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-attributesArea: Attributes (`#[…]`, `#![…]`)C-enhancementCategory: An issue proposing an enhancement or a PR with one.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @jsha@Manishearth@GuillaumeGomez@bjorn3@jyn514

        Issue actions

          rustdoc: should we stop showing `#[lang = ...]` and some other attributes? · Issue #84309 · rust-lang/rust