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: doc_cfg on trait impls needs more visibility #68100

Closed
yaahc opened this issue Jan 10, 2020 · 1 comment · Fixed by #78678
Closed

rustdoc: doc_cfg on trait impls needs more visibility #68100

yaahc opened this issue Jan 10, 2020 · 1 comment · Fixed by #78678
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

@yaahc
Copy link
Member

yaahc commented Jan 10, 2020

I'm trying to annotate all the parts of a crate that are available based on feature flags and I've had the following experience when annotating a trait impl.

#[cfg(feature = "registry")]
#[cfg_attr(docsrs, doc(cfg(feature = "registry")))]
impl<'a, L, S> LookupSpan<'a> for Layered<L, S>
where
    S: Subscriber + LookupSpan<'a>,
{
    type Data = S::Data;

    fn span_data(&'a self, id: &span::Id) -> Option<Self::Data> {
        self.inner.span_data(id)
    }
}

This is what it looks like with the default visibility

Screenshot from 2020-01-10 11-07-39

After expanding a single [+]

Screenshot from 2020-01-10 11-07-48

Fully expanded

Screenshot from 2020-01-10 11-08-00

Ideally the default visibility with everything minimized should still indicate that this trait impl is dependent upon the given feature.

@jonas-schievink jonas-schievink added 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. labels Jan 10, 2020
@WaffleLapkin
Copy link
Member

(except I'm missing something) On the latest nightly the messages couldn't be seen at all

Cargo version

% cargo --version
cargo 1.46.0-nightly (c26576f9a 2020-06-23)

The code:

#![cfg_attr(docsrs, feature(doc_cfg))]

pub struct SomeType;

pub trait SomeTrait {
    type SomeAssoc;

    fn some_method(&self);
}

#[cfg(feature = "some_feature")]
#[cfg_attr(docsrs, doc(cfg(feature = "some_feature")))]
impl SomeTrait for SomeType {
    type SomeAssoc = i32;

    fn some_method(&self) {}
}

The command:

% RUSTDOCFLAGS="--cfg docsrs" cargo doc --features "some_feature" --open

The rendered documentation:
image

Expanded:
image

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Nov 15, 2020
…GuillaumeGomez

Add tests and improve rendering of cfgs on traits

Shows the additional features required to get the trait implementation, suppressing any already shown on the current page. One interesting effect from this is if you have a cfg-ed type, implementing a cfg-ed trait (so the implementation depends on both cfgs), you will get the inverted pair of cfgs shown on each page:

![image](https://user-images.githubusercontent.com/81079/97904671-207bdc00-1d41-11eb-8144-707e8017d2b6.png)

![image](https://user-images.githubusercontent.com/81079/97904700-27a2ea00-1d41-11eb-8b9f-e925ba339044.png)

The hidden items on the trait implementation also now get the correct cfgs displayed on them.

Tests are blocked on rust-lang#78673.

fixes rust-lang#68100
cc rust-lang#43781
@bors bors closed this as completed in 7a1bd80 Nov 17, 2020
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

Successfully merging a pull request may close this issue.

3 participants