Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

warn(private_doc_tests) warns about republished items #72081

Closed
sourcefrog opened this issue May 10, 2020 · 1 comment · Fixed by #92349
Closed

warn(private_doc_tests) warns about republished items #72081

sourcefrog opened this issue May 10, 2020 · 1 comment · Fixed by #92349
Labels
A-doctests Area: Documentation tests, run by rustdoc A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@sourcefrog
Copy link
Contributor

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
@sourcefrog sourcefrog added the C-bug Category: This is a bug. label May 10, 2020
@jonas-schievink jonas-schievink added A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels May 10, 2020
jonhoo pushed a commit to jonhoo/smithy-rs that referenced this issue Jun 4, 2021
rcoh added a commit to smithy-lang/smithy-rs that referenced this issue Jun 11, 2021
* Implement Debug for more things

* Extract out generic hyper client to smithy-hyper

* Add generic fluent client generation

* Make the bounds nicer

* Make smithy-hyper hyper dep optional

* Rename smithy-hyper to smithy-client

* Enable rustls by default

* Also warn on rust 2018 idioms

* Add type-erased middleware

* Restore old DispatchLayer tracing

* Add connection type-erasure

* Fix rustdoc link

* Split up lib.rs

* Make Builder a little nicer to use

* Make aws_hyper simply wrap smithy_client

* Make it clear that bounds:: should never be implemented

* Finish adjusting aws fluent generator

* Make clippy happy

* Also re-expose test_connection in aws_hyper

* Make ktlint happy

* No Builder::native_tls with default features

Since the function "doesn't exist", we can't link to it. Arguably, the
docs should only be tested with all features enabled, but for now just
don't try to link to `native_tls`.

* Work around rustdoc bug

rust-lang/rust#72081

* Better names for type-erase methods

* Add middleware_fn

* Better docs for client

* Fix remaining erase_connector

* Better name for service in docs

* Correct send+sync test name

* Use crate name with _ in Rust code

* Fix up relative links

The standard syntax doesn't work:
rust-lang/rust#86120

* Fix the new integration test

* Hide temporary Operation type aliases

* Don't bound middleware_fn as it also bounds C

With the extra "helpful" bound, we also end up enforcing that C
implements Service, but since we're in a builder, C may not have been
set yet, and may be (), which in turn means that it isn't Service. So
users would end up with an error if they write:

    Builder::new().middleware_fn(|r| r).https().build()

but it would work with

    Builder::new().https().middleware_fn(|r| r).build()

which is silly.

Co-authored-by: Russell Cohen <rcoh@amazon.com>
rcoh added a commit to smithy-lang/smithy-rs that referenced this issue Jun 11, 2021
…#496)

* Implement Debug for more things

* Extract out generic hyper client to smithy-hyper

* Add generic fluent client generation

* Make the bounds nicer

* Make smithy-hyper hyper dep optional

* Rename smithy-hyper to smithy-client

* Enable rustls by default

* Also warn on rust 2018 idioms

* Add type-erased middleware

* Restore old DispatchLayer tracing

* Add connection type-erasure

* Fix rustdoc link

* Split up lib.rs

* Make Builder a little nicer to use

* Make aws_hyper simply wrap smithy_client

* Make it clear that bounds:: should never be implemented

* Finish adjusting aws fluent generator

* Make clippy happy

* Also re-expose test_connection in aws_hyper

* Make ktlint happy

* No Builder::native_tls with default features

Since the function "doesn't exist", we can't link to it. Arguably, the
docs should only be tested with all features enabled, but for now just
don't try to link to `native_tls`.

* Work around rustdoc bug

rust-lang/rust#72081

* Better names for type-erase methods

* Add middleware_fn

* Better docs for client

* Fix remaining erase_connector

* Better name for service in docs

* Correct send+sync test name

* Use crate name with _ in Rust code

* Fix up relative links

The standard syntax doesn't work:
rust-lang/rust#86120

* Fix the new integration test

* Hide temporary Operation type aliases

* Don't bound middleware_fn as it also bounds C

With the extra "helpful" bound, we also end up enforcing that C
implements Service, but since we're in a builder, C may not have been
set yet, and may be (), which in turn means that it isn't Service. So
users would end up with an error if they write:

    Builder::new().middleware_fn(|r| r).https().build()

but it would work with

    Builder::new().https().middleware_fn(|r| r).build()

which is silly.

* Don't recursive infinitely

* Can only doc(inline) re-exports, not type alises

* Can only doc(inline) re-exports, not type alises

Co-authored-by: Russell Cohen <rcoh@amazon.com>
@Oliboy50
Copy link

related issue: awslabs/aws-sdk-rust#156

@jyn514 jyn514 added the A-doctests Area: Documentation tests, run by rustdoc label Sep 21, 2021
@bors bors closed this as completed in 4d0b567 Jan 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-doctests Area: Documentation tests, run by rustdoc A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants