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

[beta regression] missing_docs lint ignores items generated by external macros #53537

Closed
durka opened this issue Aug 20, 2018 · 4 comments
Closed
Labels
A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. C-bug Category: This is a bug. regression-from-stable-to-beta Performance or correctness regression from stable to beta. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.
Milestone

Comments

@durka
Copy link
Contributor

durka commented Aug 20, 2018

On beta and nightly, items generated by macros in external crates do not have to be documented, even in the presence of #![deny(missing_docs)].

Consider this code: https://gist.github.com/0dda35f371bdde94780fc65bb99c4bf0

Now observe the reaction! Compiling with stable:

$ cargo +stable build
   Compiling b v0.1.0 (file:///Users/alex/Documents/work/macdoc/b)
   Compiling a v0.1.0 (file:///Users/alex/Documents/work/macdoc/a)
error: missing documentation for a function
  --> src/lib.rs:8:9
   |
8  |         pub fn $f() {}
   |         ^^^^^^^^^^^
...
14 | a!(bar, Bar);
   | ------------- in this macro invocation
   |
note: lint level defined here
  --> src/lib.rs:1:9
   |
1  | #![deny(missing_docs)]
   |         ^^^^^^^^^^^^

error: missing documentation for a struct
  --> src/lib.rs:10:9
   |
10 |         pub struct $g;
   |         ^^^^^^^^^^^^^^
...
14 | a!(bar, Bar);
   | ------------- in this macro invocation

error: missing documentation for a function
  --> src/lib.rs:15:1
   |
15 | b!(foo, Foo);
   | ^^^^^^^^^^^^^
   |
   = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info)

error: missing documentation for a struct
  --> src/lib.rs:15:1
   |
15 | b!(foo, Foo);
   | ^^^^^^^^^^^^^
   |
   = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info)

error: aborting due to 4 previous errors

error: Could not compile `a`.

To learn more, run the command again with --verbose.

And with beta:

$ cargo +beta build
   Compiling b v0.1.0 (file:///Users/alex/Documents/work/macdoc/b)
   Compiling a v0.1.0 (file:///Users/alex/Documents/work/macdoc/a)
error: missing documentation for a function
  --> src/lib.rs:8:9
   |
8  |         pub fn $f() {}
   |         ^^^^^^^^^^^
...
14 | a!(bar, Bar);
   | ------------- in this macro invocation
   |
note: lint level defined here
  --> src/lib.rs:1:9
   |
1  | #![deny(missing_docs)]
   |         ^^^^^^^^^^^^

error: missing documentation for a struct
  --> src/lib.rs:10:9
   |
10 |         pub struct $g;
   |         ^^^^^^^^^^^^^^
...
14 | a!(bar, Bar);
   | ------------- in this macro invocation

error: aborting due to 2 previous errors

error: Could not compile `a`.

To learn more, run the command again with --verbose.

Note only the two errors!

cc: @Dylan-DPC

@djrenren
Copy link
Contributor

Yeah looks like the lint here:

declare_lint! {
pub MISSING_DOCS,
Allow,
"detects missing documentation for public members"
}

needs report_in_external_macro: true.

So it would be:

 declare_lint! { 
     pub MISSING_DOCS, 
     Allow, 
     "detects missing documentation for public members",
     report_in_external_macro: true
} 

(yeah the syntax is super funky).

Would be a good first issue for someone, if they're so inclined.

@durka
Copy link
Contributor Author

durka commented Aug 21, 2018

Would be a good first issue for someone, if they're so inclined.

Needs to be done in time to be backported. Next release is 9/13.

@kennytm kennytm added A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. regression-from-stable-to-beta Performance or correctness regression from stable to beta. C-bug Category: This is a bug. labels Aug 21, 2018
@kennytm kennytm added this to Triaged in 1.29 regressions via automation Aug 21, 2018
@Dylan-DPC-zz
Copy link

I'll add the key now. I don't now how do we test this though

@kennytm kennytm moved this from Triaged to Fix in progress in 1.29 regressions Aug 21, 2018
@alexcrichton alexcrichton added this to the 1.29 milestone Aug 21, 2018
@nikomatsakis nikomatsakis added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Aug 23, 2018
@nikomatsakis
Copy link
Contributor

triage: P-high

kennytm added a commit to kennytm/rust that referenced this issue Aug 24, 2018
@pietroalbini pietroalbini moved this from Fix in progress to Backport in progress in 1.29 regressions Aug 25, 2018
@pietroalbini pietroalbini moved this from Backport in progress to Fixed in 1.29 regressions Aug 27, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-lint Area: Lints (warnings about flaws in source code) such as unused_mut. C-bug Category: This is a bug. regression-from-stable-to-beta Performance or correctness regression from stable to beta. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.
Projects
No open projects
Development

No branches or pull requests

6 participants