rustdoc: Tracking issue for command-line flag `--show-coverage`

[GuillaumeGomez]

FIXME: Write a proper synopsis.

Note

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.

A tracking issue is however not meant for large scale discussion, questions, or bug reports.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.

Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

• Implementation PR
• Stabilization PR

Implementation history

FIXME: Recover the history.

[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