Skip to content

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

Open
Open
rustdoc: Tracking issue for command-line flag --show-coverage#58154
Labels
A-doc-coverageArea: Calculating how much of a crate has documentationB-unstableBlocker: Implemented in the nightly compiler and unstable.C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCS-tracking-needs-summaryStatus: It's hard to tell what's been done and what hasn't! Someone should do some investigation.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Description

@GuillaumeGomez
GuillaumeGomez
opened on Feb 4, 2019

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.

Activity

  1. GuillaumeGomez
    added
    T-rustdocRelevant 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
    QuietMisdreavus
    on Feb 5, 2019
    Contributor

    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
    GuillaumeGomez
    on Feb 5, 2019
    MemberAuthor

    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
    sanxiyn
    on Mar 21, 2019
    Contributor

    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
    QuietMisdreavus
    on Mar 21, 2019
    Contributor

    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.

  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 RFC
    on Mar 21, 2019
  10. jonas-schievink
    added
    B-unstableBlocker: Implemented in the nightly compiler and unstable.
    on Apr 25, 2019

  11. steveklabnik commented on Apr 21, 2020

    @steveklabnik
    steveklabnik
    on Apr 21, 2020
    Contributor

    Triage: this flag is still unstable.

  12. jyn514
    added
    A-doc-coverageArea: Calculating how much of a crate has documentation
    on Aug 30, 2020

  13. Nemo157 commented on Oct 5, 2020

    @Nemo157
    Nemo157
    on Oct 5, 2020
    Contributor

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

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

  15. GuillaumeGomez commented on Dec 5, 2023

    @GuillaumeGomez
    GuillaumeGomez
    on Dec 5, 2023
    MemberAuthor

    What do you mean?

    EDIT: About the "Could I bump this?"

  16. awwsmm commented on Dec 5, 2023

    @awwsmm
    awwsmm
    on Dec 5, 2023

    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.

  17. GuillaumeGomez commented on Dec 5, 2023

    @GuillaumeGomez
    GuillaumeGomez
    on Dec 5, 2023
    MemberAuthor

    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
    crumblingstatue
    on Oct 21, 2024
    Contributor

    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.
    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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-doc-coverageArea: Calculating how much of a crate has documentationB-unstableBlocker: Implemented in the nightly compiler and unstable.C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCS-tracking-needs-summaryStatus: It's hard to tell what's been done and what hasn't! Someone should do some investigation.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions