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

Doc comments causing build errors #83492

Closed
hquil opened this issue Mar 25, 2021 · 2 comments · Fixed by #86813
Closed

Doc comments causing build errors #83492

hquil opened this issue Mar 25, 2021 · 2 comments · Fixed by #86813
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-parser Area: The parsing of Rust source code to an AST C-enhancement Category: An issue proposing an enhancement or a PR with one. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.

Comments

@hquil
Copy link

hquil commented Mar 25, 2021

rustc 1.51.0 (2fd73fabe 2021-03-23)
rustc 1.53.0-nightly (07e0e2ec2 2021-03-24)

Docstrings placed at a few selected positions that cause either a warning (good), an unrelated error (bad) or both (ugly).

fn good(num: u8) -> bool {	
   match num {
      3 => true,
      /// warning: unused doc comment
      _ => false,
   }
}

fn bad(num: u8) -> bool {
   if num == 3 {
      true
   }
   /// error[E0308]: mismatched types
   /// error: expected expression, found keyword `else`
   else {
      false
   }
}

fn ugly(num: u8) -> bool {
   /// error[E0658]: attributes on expressions are experimental
   /// warning: unused doc comment
   num == 3
}

On the third example we at least get an additional warning to point us in the right direction.
The second example can become nightmare to catch :3

@hquil hquil added A-diagnostics Area: Messages for errors, warnings, and lints T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Mar 25, 2021
@jyn514 jyn514 added the A-parser Area: The parsing of Rust source code to an AST label Mar 26, 2021
@JohnTitor
Copy link
Member

JohnTitor commented Mar 26, 2021

Note that the doc comment is equal to #[doc("")] so all the errors/warnings are valid. On ugly, it should be reasonable to emit an error and a warning both since it isn't straightforward to have the user add a feature flag and remove the error, to tell that rustdoc doesn't do anything there. On bad, we could improve the diagnostics by recovering at some point, I imagine.

@JohnTitor JohnTitor added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Mar 26, 2021
@scottmcm
Copy link
Member

I concur that errors for these things are absolutely by design. One can always use normal // comments in these places.

So at most this is a "would be nice if the error hinted removing a /" issue, I think.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-parser Area: The parsing of Rust source code to an AST C-enhancement Category: An issue proposing an enhancement or a PR with one. T-compiler Relevant to the compiler 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