[rustdoc] Tracking issue for --show-coverage

[GuillaumeGomez]

cc @QuietMisdreavus

[QuietMisdreavus]

I have a in-progress branch locally that i haven't pushed with this. The current idea is that you send an additional flag to rustdoc that makes it count items in the crate, and print something like the following instead of generating docs:

Rustdoc found 642/806 items with documentation (634/634 not counting trait impls)
    Score: 79.7% (100.0% not counting trait impls)

The reason it counts trait impls separately is because trait impls can have their own documentation, but if you don't add docs it inherits from the trait's own docs.

Right now, the following items are not counted:

• inherent impl blocks
• built-in derived impls (with the #[automatically_derived] attribute)
• private/#[doc(hidden)] items (i plan on combining this with --document-private-items to get a separate coverage count for private items)
• pub use/pub extern crate statements, since those doc comments are not printed
• re-exported items that came from another crate

There's an outstanding question on whether we can detect whether a trait impl came from a derive macro (e.g. most of the undocumented trait impls in that sample came from #[derive(Serialize)]), but detecting that seems to be more difficult than i anticipated.

I've also got a thing right now where if you pass both the new flag and --verbose, it prints the undocumented items it found:

(...lots more lines above this...)
Missing docs on egg_mode::{impl Stream for UserSearch<'a>}
Missing docs on egg_mode::{impl Stream for UserSearch<'a>}::Item
Missing docs on egg_mode::{impl Stream for UserSearch<'a>}::Error
Missing docs on egg_mode::{impl Stream for UserSearch<'a>}::poll
Missing docs on egg_mode::{impl Stream for CursorIter<'a, T>}
Missing docs on egg_mode::{impl Stream for CursorIter<'a, T>}::Item
Missing docs on egg_mode::{impl Stream for CursorIter<'a, T>}::Error
Missing docs on egg_mode::{impl Stream for CursorIter<'a, T>}::poll
Missing docs on egg_mode::{impl Stream for TwitterStream}
Missing docs on egg_mode::{impl Stream for TwitterStream}::Item
Missing docs on egg_mode::{impl Stream for TwitterStream}::Error
Missing docs on egg_mode::{impl Stream for TwitterStream}::poll
Missing docs on egg_mode::{impl Deserialize<'de> for TwitterUser}
Missing docs on egg_mode::{impl Deserialize<'de> for TwitterUser}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for Tweet}
Missing docs on egg_mode::{impl Deserialize<'de> for Tweet}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for SearchResult<'static>}
Missing docs on egg_mode::{impl Deserialize<'de> for SearchResult<'static>}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for SearchResult}
Missing docs on egg_mode::{impl Deserialize<'de> for SearchResult}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for DirectMessage}
Missing docs on egg_mode::{impl Deserialize<'de> for DirectMessage}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for RateLimitStatus}
Missing docs on egg_mode::{impl Deserialize<'de> for RateLimitStatus}::deserialize
Missing docs on egg_mode::{impl Deserialize<'de> for StreamMessage}
Missing docs on egg_mode::{impl Deserialize<'de> for StreamMessage}::deserialize
Rustdoc found 642/806 items with documentation (634/634 not counting trait impls)
    Score: 79.7% (100.0% not counting trait impls)
    Finished dev [unoptimized + debuginfo] target(s) in 4.34s

...granted, this is very similar to the missing-docs lint, so this may not be completely useful.

[GuillaumeGomez]

Maybe not but at least it allows to have an easy option to directly get a documentation coverage result.

[sanxiyn]

Fixed by #58626.

[QuietMisdreavus]

Since the feature is unstable, i'm going to reopen this issue to repurpose it as a tracking issue. I want to try adding a JSON output option to it, for ease of automatic checking, and then i'd like to integrate it into bootstrap or our CI if possible.

[steveklabnik]

Triage: this flag is still unstable.

[Nemo157]

I don't have time to write a proper bug ticket for it, but when using --show-coverage with roaring 0.6.1 the impl blocks from other files seem to be ignored, giving a total of 9 items rather than the 50-something there actually are.

EDIT: 4 years later: #129007

[awwsmm]

Could I bump this? I would really love this feature, and it's been a while since there were any updates here.

[GuillaumeGomez]

What do you mean?

EDIT: About the "Could I bump this?"

[awwsmm]

I meant "could I refresh the attention of whoever had been working on this." From the comments here, it looks like the effort to stabilize this flag has stalled. I'd offer to help, but I'm pretty new to Rust.

[GuillaumeGomez]

Ah I see. Well, we need to make an RFC for that. If you're motivated to write it (which needs to describe exactly which item is part of the count etc), I can help.

[crumblingstatue]

Could it be possible for the coverage report to take into account scraped examples (-Zrustdoc-scrape-examples)?
One might not want to make custom examples for all items if scraped examples suffice.