maybe add an example from #10229 which is a common pitfall (in particular #10229 (comment)), which was closed as wontfix due to noone having stepped up to work on it

One that I almost reported separately is

type
  Odd = ref object
    id: int

proc `=copy`(dest: var Odd; source: Odd) {.error.}

Which yields

Error: signature for '=copy' must be proc[T: object](x: var T; y: T)

What I didn't notice until I was writing up the issue is that the T: object is the important information there: the code is providing a ref object instead. So rather than change the text of the error, I think this would be another good candidate for an --explain feature.

I'll give this feature a try.

and yet another bug report that was just filed that's the same as this: #16232

I'm bumping this up to medium priority since it seems to trip so many people (and would generally improve user experience for everyone)

Since my issue is a duplicate of this one, I'll write my findings here

@timotheecour I kind of got curious, and started looking into the parser code to debug it for my cases. I narrowed it down to the optPar(). In my case, it is in parserPar(). The messesage comes about because the parser has moved on to the next token, EOF, causing the indentation level to reset. optPar is correctly looking for a something with a higher or equal to indentation, but the condition is not met.

Looking into the grammer, I believe optPar – optional paragraphs? – is used through out to handle when syntax is split across lines.

If this was useful, I am happy to look into the other cases and sees what's going on.

@NebulaFox please make a PR since you've started looking at this; I'd recommend focusing on improving at least just 1 common case for a start.
for example:

proc fn() {.exportc.}
  echo 1

Error: invalid indentation

=> instead:

Error: invalid indentation or missing `=` at main.nim(1,22)

@timotheecour I have not done any code changes yet, just debugging at the moment.

Looking at the case that you have provided, I think error message invalid indentation is wrong for a different reason. It occurs in indAndComment under parseRoutine. Through trial and error, I have concluded that indAndComment is parsing for doc comments. Looking at the grammer, since doc comments are optional, I do not currently understand why incAndComment is emitting an error.

I could create a PR with removal of the emitting error in indAndComment to get the ball rolling?

Removing the emitting error from incAndComment we end up in another invalid indentation error but this time it is correct. It occurs in parseTopLevelStmt. From the grammar, the equals, =, that is used to define the implementation is optional. So the example is parsed as a definition of fn() and a top level echo statement that is incorrectly indented. The message of the error could be changed to be more clearer, top level statement is incorrectly indented.

proc fn() {.exportc.}
  echo 1

Ideally we want the parser to mention a missing equals when it detects something that looks like an implementation on a procedure. The parser only has history as far back as the context it is in. The context of parseTopLevelStmt would not allow us to say there is possibily of a missing equals.

As far as I can see, the parser is behaving correctly, but lacks anyway to infer user intent. I propose that we add a layer, to or above, the parser, that can then keep track of things to infer user intent to give better error messages. We can then use the above cases to test the compiler against and determine the correct error message. I am not fully aware if the test suit is capable of handling such integration test/blackboxing testing.

Thoughts?

I have a candidate PR: timotheecour#418 that fixes 1 of the most common issues:

I am not fully aware if the test suit is capable of handling such integration test/blackboxing testing.

the test suite (tests/) can do anything, including calling the compiler directly and verifying the error message you get is as expected

An unneeded closing parenthesis triggers the Error: invalid indentationmessage.

I guess something like Error: Unmatched parenthesis would be better in this case:

try:
  a = client.getContent(arg1 & arg2.getStr)
except:
  echo "Error when requesting network API:" , arg2.getStr)     =====> Error: invalid indentation
  continue

#16397 was merged; see future work mentioned in that PR