Rust: Doc comments present after a particular syntax error cause an unhelpful error message to be output.

[toor]

I had this code:

pub struct LocalApic {
    pub id: u8
    /// The id of the parent core
    pub processor_id: u8,
    // ...
}

The actual error of course here, would be that there is a missing comma after the pub id: u8.
However the error message given by the compiler was:

error[E0585]: found a documentation comment that doesn't document anything
  --> src/device/apic.rs:16:5
   |
16 |     /// The id of the parent core.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: doc comments must come before what they document, maybe a comment was intended with //?
``````
which is irrelevant to the actual error present in the code and does nothing but mislead the programmer IMO.

It is worth noting that attaching `#[doc]` to the line `pub processor_id: u8` does give the expected error:

error: expected ,, or }, found #
--> src/device/apic.rs:16:5
|
16 | #[doc = "The id of the parent core"]
| ^
|
= help: struct fields should be separated by commas
```

This isn't a particularly important issue, but as mentioned by someone I spoke to regarding this error, the error messages given by the compiler are usually very helpful, and I feel it is worth maintaining this standard.

[tinaun]

to fix this, https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs#L5650 should emit the error for a useless doc comment and a missing comma / brace if it encounters both - right now doc comment errors override missing seperators completely.

#[doc] attributes work fine because they are not parsed as a single doc comment token.

[PramodBisht]

@tinaun @estebank Can I take this one if nobody is working on that?

[estebank]

@PramodBisht go ahead! Feel free to ask for help if you need. If this is your first contribution, take a look at https://forge.rust-lang.org/x-py.html for setting up the environment.

[PramodBisht]

@estebank , Now console output is coming like this

error[E0585]: found a documentation comment that doesn't document anything
 --> /tmp/test.rs:3:5
  |
3 |     /// the id of the parent core
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: doc comments must come before what they document, maybe a comment was intended with `//`?

error: expected `,`, or `}`, found `/// the id of the parent core`
 --> /tmp/test.rs:3:5
  |
3 |     /// the id of the parent core
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: struct fields should be separated by commas

error[E0601]: main function not found

error: aborting due to 3 previous errors

You've got a few errors: E0585, E0601
If you want more information on an error, try using "rustc --explain E0585"

Now I have three quick questions for you.
1) In the case when a comma is missing for middle fields of struct, should we avoid showing doc warning, because we have not parsed below fields yet?
2) Should I consider creating a new entry in Error enum to handle comma warning?
3) If we have decided to show both comma and doc warning, how important it is to show comma missing warning before doc warning?

[estebank]

@PramodBisht I would elide the missing comma error. Create a PR with r? @estebank in its body so that I'm assigned as reviewer and we can discuss in the context of the code. It seems like you're in the right path. Depending on how the code is laid out, you might be able to try to consume a , without failing if it isn't there depending on the success or failure of the previous field.

[PramodBisht]

@estebank PR raised