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

rustdoctest: no allow lints are put in doctests, contradicting Rustdoc Book #45750

Closed
QuietMisdreavus opened this issue Nov 3, 2017 · 2 comments
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@QuietMisdreavus
Copy link
Member

image

In the current Rustdoc Book, it mentions that a few lints are automatically allowed in doctests:

Some common allow attributes are inserted, including unused_variables, unused_assignments, unused_mut, unused_attributes, and dead_code. Small examples often trigger these lints.

However, as the image above demonstrates, this does not seem to be the case. I have not added any #![doc(test(attr(warn(unused))))] or similar attributes to my crate, which would override such behavior. These warnings are usually suppressed, but adding --nocapture when running tests shows these warnings. (It also shows more important warnings, like unused_must_use, which helped in a different library of mine.)

@rust-lang/docs @rust-lang/dev-tools - Is this a docs issue (which would mean removing this entry from the Rustdoc Book) or a rustdoc issue (which would mean making sure these items are added)?

@kennytm kennytm added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-dev-tools-rustdoc A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Nov 4, 2017
@GuillaumeGomez
Copy link
Member

I think it should be added into rustdoc instead (but I was sure it was already...).

@QuietMisdreavus
Copy link
Member Author

I've opened #45764 to add a blanket #![allow(unused)] when a crate doesn't specify any attributes via #![doc(test(attr(...)))]. I also opened #45767 to document #![doc(test(attr(...)))] itself.

kennytm added a commit to kennytm/rust that referenced this issue Nov 7, 2017
…ts, r=GuillaumeGomez

rustdoc: add #[allow(unused)] to every doctest

More information in rust-lang#45750 - this is behavior that was documented but not actually implemented.

I also reordered how outer attributes are applied to doctests. Previously, attributes from `#![doc(test(attr(...)))]` would be applied *after* attributes from within the test itself, meaning if a doctest tried to override lints that would be set crate-wide, it wouldn't work at all. This gives a better scope of how lints can be applied.

Closes rust-lang#45750
kennytm added a commit to kennytm/rust that referenced this issue Nov 7, 2017
…ts, r=GuillaumeGomez

rustdoc: add #[allow(unused)] to every doctest

More information in rust-lang#45750 - this is behavior that was documented but not actually implemented.

I also reordered how outer attributes are applied to doctests. Previously, attributes from `#![doc(test(attr(...)))]` would be applied *after* attributes from within the test itself, meaning if a doctest tried to override lints that would be set crate-wide, it wouldn't work at all. This gives a better scope of how lints can be applied.

Closes rust-lang#45750
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Nov 18, 2017
…ol, r=frewsxcv

rustdoc book: talk about #![doc(test(no_crate_inject))] and #![doc(test(attr(...)))]

While investigating rust-lang#45750 i noticed that `#![doc(test(attr(...)))]` wasn't documented at all. Since this is useful for making your examples follow the same coding guidelines as your code, i wanted to add it to the Rustdoc Book. I also added `#![doc(test(no_crate_inject))]` since it's used in the same place and might be useful for macro-heavy crates. I added mentions for these to "The `doc` attribute" as well as "Documentation tests" since it's useful information in both places.

Technically the step reordering in the second commit is gated on rust-lang#45764, since before that lands attributes from the doctest come before the ones from `#![doc(test(attr(...)))]`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

3 participants