rustdoc: Tracking issue for command-line flag --show-coverage #58154

Activity

1. GuillaumeGomez

   added

   T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.Relevant to the rustdoc team, which will review and decide on the PR/issue.

   on Feb 4, 2019
2. QuietMisdreavus commented on Feb 5, 2019

   

   QuietMisdreavus

   on Feb 5, 2019

   Contributor

   More actions

   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.
3. GuillaumeGomez commented on Feb 5, 2019

   

   GuillaumeGomez

   on Feb 5, 2019

   MemberAuthor

   More actions

   Maybe not but at least it allows to have an easy option to directly get a documentation coverage result.
4. sanxiyn commented on Mar 21, 2019

   

   sanxiyn

   on Mar 21, 2019

   Contributor

   More actions

   Fixed by #58626.
5. sanxiyn

   closed this as completedon Mar 21, 2019
6. QuietMisdreavus

   changed the title [-][rustdoc] add a coverage option[/-] [+][rustdoc] Tracking issue for `--show-coverage`[/+] on Mar 21, 2019
7. QuietMisdreavus commented on Mar 21, 2019

   

   QuietMisdreavus

   on Mar 21, 2019

   Contributor

   More actions

   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.

   🎉React with 🎉1Reacted by Phil Hansch
8. QuietMisdreavus

   reopened this on Mar 21, 2019
9. QuietMisdreavus

   added

   C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCCategory: An issue tracking the progress of sth. like the implementation of an RFC

   on Mar 21, 2019
10. jonas-schievink

    added

    B-unstableBlocker: Implemented in the nightly compiler and unstable.Blocker: Implemented in the nightly compiler and unstable.

    on Apr 25, 2019
11. steveklabnik commented on Apr 21, 2020

    

    steveklabnik

    on Apr 21, 2020

    Contributor

    More actions

    Triage: this flag is still unstable.
12. jyn514

    added

    A-doc-coverageArea: Calculating how much of a crate has documentationArea: Calculating how much of a crate has documentation

    on Aug 30, 2020
13. Nemo157 commented on Oct 5, 2020

    

    Nemo157

    on Oct 5, 2020

    Last edited by Nemo157

    Contributor

    More actions

    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
14. awwsmm commented on Dec 5, 2023

    

    awwsmm

    on Dec 5, 2023

    More actions

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

    👍React with 👍1Reacted by Alexander Cyon
15. GuillaumeGomez commented on Dec 5, 2023

    

    GuillaumeGomez

    on Dec 5, 2023

    Last edited by GuillaumeGomez

    MemberAuthor

    More actions

    What do you mean?

    EDIT: About the "Could I bump this?"
16. awwsmm commented on Dec 5, 2023

    

    awwsmm

    on Dec 5, 2023

    More actions

    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.

    👍React with 👍1Reacted by Alexander Cyon
17. GuillaumeGomez commented on Dec 5, 2023

    

    GuillaumeGomez

    on Dec 5, 2023

    MemberAuthor

    More actions

    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.
18. crumblingstatue commented on Oct 21, 2024

    

    crumblingstatue

    on Oct 21, 2024

    Contributor

    More actions

    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.
19. fmease

    added

    S-tracking-needs-summaryStatus: It's hard to tell what's been done and what hasn't! Someone should do some investigation.Status: It's hard to tell what's been done and what hasn't! Someone should do some investigation.

    on Oct 10, 2025
20. fmease

    changed the title [-][rustdoc] Tracking issue for `--show-coverage`[/-] [+]rustdoc: Tracking issue for command-line flag `--show-coverage`[/+] on Oct 10, 2025
21. bh2smith

    added a commit that references this issue on Jun 19, 2026

    fix: make doc-coverage nightly pin effective (#48)

    ...

    b406e29