Skip to content

warn(private_doc_tests) warns about republished items #72081

Closed
@sourcefrog

Description

@sourcefrog

I have doctests on a type in a private module, that's then republished into the crate's top-level module. I think this is a pretty common pattern in Rust?

Here's a simplified example:

// lib.rs
#[warn(private_doc_tests)]
mod inner {
    /// This is my struct.
    ///
    /// You can make a struct:
    ///
    /// ```
    /// A{}
    /// ```
    pub struct A {}
}

pub use inner::A;

If you run rustdoc on this, you'll see

  1. The example is visible under the top-level A struct.
  2. You get a warning about "documentation test in private item"
 Documenting rustdoc-warning-example v0.1.0 (/Users/mbp/src/rustdoc-warning-example)
warning: documentation test in private item
 --> src/lib.rs:3:5
  |
3 | /     /// This is my struct.
4 | |     ///
5 | |     /// You can construct it:
6 | |     ///
7 | |     /// ```
8 | |     /// A{}
9 | |     /// ```
  | |___________^
  |
note: the lint level is defined here
 --> src/lib.rs:1:8
  |
1 | #[warn(private_doc_tests)]
  |        ^^^^^^^^^^^^^^^^^

warning: documentation test in private item
 --> src/lib.rs:3:5
  |
3 | /     /// This is my struct.
4 | |     ///
5 | |     /// You can construct it:
6 | |     ///
7 | |     /// ```
8 | |     /// A{}
9 | |     /// ```
  | |___________^

warning: 2 warnings emitted

If you run rustdoc, it does build and run the test.

I expected there would not be a warning, because the doctest is both visible to users, and run. In other words the warning ought to match whether the item is actually visible.

Also, it seems like a glitch that the warning is reported twice.

Follows on from #55333, #55367, cc @GuillaumeGomez.

Meta

rustc --version --verbose:

rustc 1.44.0-beta.2 (b1162ed50 2020-04-25)
binary: rustc
commit-hash: b1162ed5067784cff2bb06afa8910510bf43e2bf
commit-date: 2020-04-25
host: x86_64-apple-darwin
release: 1.44.0-beta.2
LLVM version: 9.0

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-doctestsArea: Documentation tests, run by rustdocA-lintsArea: Lints (warnings about flaws in source code) such as unused_mut.C-bugCategory: This is a bug.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