Splitting the diagnostic text field into a summary field and a reason field

Clang Frontend
3

@cjdb could you add some examples to this proposal how this reason field would be used? I am specifically interested in what information would we add to the Reason field instead of emitting an additional note.

In general, I agree with the direction of making warning messages more structured internally, I just want to avoid confusions about when to emit notes when to add a reason etc. Preferably, we should have clear guidelines on these.

tl;dr I don’t think there’s a clear boundary between the two, and it will take time to produce advice. For now, we should continue to write notes, as the new diagnostic model is far off into the horizon. A summary should be considered the headline of the diagnostic, such as candidate template ignored; and the reason should be what follows that, such as expected a type, got a class template.

Ideally, when in structured output mode, notes would become a part of the error/warning/remark. Although it conflates a few ideas, the web-based section of my original proposal demos the distinction between a summary, a reason, and context (notes are a form of context). If you’re interested in the phrasing component, please head over to Let’s get Clang diagnostics translatable! for that discussion.

SARIF doesn’t yet support the model I’d like to see, but here’s what it would roughly look like as an arbitrary JSON object:

{
  "summary": "we couldn't instantiate `llvm::sort(Locations)`",
  "source_location": {
    "path": "/tmp/llvm-project/clang/lib/Lex.cpp",
    "line": 512,
    "column": 81
  },
  "reason": "`llvm::sort` tried to add `std::list<SourceLocation>::iterator` with an `int `, but we can't find an appropriate `operator+` overload.",
  "snippet": "...",
  "notes": [
    // contains overload candidates, template instantiation (if necessary)
  ]
}

There are various things about phrasing and diagnostic emission order here that make the above example substantially different to the status quo, and those are off-topic here. What is interesting in this discussion is that the summary explains what is wrong (we couldn’t instantiate a template), and the reason augments the summary by briefly explaining why compilation failed (the template does something our parameter doesn’t support). Notes are then used to provide additional, probably more detailed, insight into the problem.