Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rustdoc: The short description of #[doc(cfg(target_feature = ...))] shouldn't spell out "target feature" #49334

Closed
kennytm opened this issue Mar 24, 2018 · 1 comment
Assignees
Labels
C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@kennytm
Copy link
Member

kennytm commented Mar 24, 2018

The words "target feature" are redundant

rustdoc's short description of #[doc(cfg(target_feature = ...))] is showing something like [x86-64 and target feature avx]. The words "target feature" is unnecessary since usually it is clear what avx means from context, i.e. [x86-64 and avx] should be clear enough.

@kennytm kennytm added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-enhancement Category: An issue proposing an enhancement or a PR with one. labels Mar 24, 2018
@QuietMisdreavus
Copy link
Member

Notes to self:

The issue at hand is the fact that the "short text" is overridden when the condition is combined with others. The target features are supposed to only show "avx" when they're by themselves, as shown in the OP of #48759. The offending snippet:

impl<'a> fmt::Display for ShortHtml<'a> {
fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
match *self.0 {
Cfg::Cfg(ref name, Some(ref vendor)) if name == &"target_feature" => {
write!(fmt, "<code>{}</code>", vendor)
},
ref cfg => write!(fmt, "{}", Html(cfg)),
}
}
}

The easiest way to fix this is to never print "target feature", even in the long form, but that text is still valuable there.

kennytm added a commit to kennytm/rust that referenced this issue May 22, 2018
…uillaumeGomez

rustdoc: use "short form" doc(cfg) printing even when combined with other conditionals

Fixes rust-lang#49334

The original "short form" printing was introduced when `target_feature` was added to the `doc(cfg)` handling. However, it didn't properly propagate the "short form" indicator if the cfg was a combination of multiple conditionals, so the linked issue happened. This changes the handling to use a bool in the original `Html` wrapper, rather than a separate wrapper struct that defers to the original one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: An issue proposing an enhancement or a PR with one. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

2 participants