Confusing error message "this doc comment doesn't document anything" when there is a syntax error right after a comment

[ipkiss42]

I tried this code:

/// Some documentation. Below "async" is before "pub" by mistake.
async pub fn hello() {}

fn main() {
}

I expected to see this happen: a clear error message telling me about the mistake (async before pub).

Instead, this happened:

error: expected item after doc comment
 --> src/main.rs:1:1
  |
1 | /// Some documentation. Below "async" is before "pub" by mistake.
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this doc comment doesn't document anything

This is a confusing error message. Without the comment, the error is clearer (though arguably still not completely obvious):

error: expected item, found keyword `async`
 --> src/main.rs:1:1
  |
1 | async pub fn hello() {}
  | ^^^^^ expected item

Meta

rustc --version --verbose:

rustc 1.43.0
binary: rustc
commit-hash: unknown
commit-date: unknown
host: x86_64-unknown-linux-gnu
release: 1.43.0
LLVM version: 10.0

Backtrace

No backtrace.

[edward-shen]

Agreed, I just hit this as well. It also seems to be inconsistent based on the syntax error. For example, a missing identifier syntax error outputs a helpful error

/// hello world
async fn {}

error: expected identifier, found `{`
 --> src/lib.rs:2:10
  |
2 | async fn {}
  |          ^ expected identifier

while a different syntax error prints out a different error than the first one:

/// hello world
<>

error[E0585]: found a documentation comment that doesn't document anything
 --> src/lib.rs:1:1
  |
1 | /// hello world
  | ^^^^^^^^^^^^^^^
  |
  = help: doc comments must come before what they document, maybe a comment was intended with `//`?

[estebank]

Current output:

error: expected one of `extern`, `fn`, or `unsafe`, found keyword `pub`
 --> src/main.rs:2:7
  |
2 | async pub fn hello() {}
  | ------^^^
  | |     |
  | |     expected one of `extern`, `fn`, or `unsafe`
  | help: visibility `pub` must come before `async`: `pub async`

The following case is still subpar

/// hello world
<>

[RedL0tus]

The following code snippet can trigger this bug as well:

enum TestEnum {
    Works,
    /// Some documentation
    Self,
}

Current output:

error[E0585]: found a documentation comment that doesn't document anything
 --> test_enum.rs:3:5
  |
1 | enum TestEnum {
  |      -------- while parsing this enum
2 |     Works,
3 |     /// Some documentation
  |     ^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: doc comments must come before what they document, if a comment was intended use `//`
  = help: enum variants can be `Variant`, `Variant = <integer>`, `Variant(Type, ..., TypeN)` or `Variant { fields: Types }`

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0585`.

Expected output:

error: expected identifier, found keyword `Self`
 --> test_enum.rs:4:5
  |
1 | enum TestEnum {
  |      -------- while parsing this enum
...
4 |     Self,
  |     ^^^^ expected identifier, found keyword
  |
  = help: enum variants can be `Variant`, `Variant = <integer>`, `Variant(Type, ..., TypeN)` or `Variant { fields: Types }`

error: aborting due to 1 previous error