This change introduces a new literate API for reporting analyzer
diagnostics. The new API looks like this:
diagnosticReporter.reportError(
diagnosticCode
.withArguments(...) // omitted if diagnostic takes no arguments
.withContextMessages(contextMessages) // may be omitted
.at(astNode),
);
For comparison, the old API looks like this:
diagnosticReporter.atNode(
astNode,
diagnosticCode,
arguments: [...], // omitted if diagnostic takes no arguments
contextMessages: contextMessages, // may be omitted
);
For the moment, this new API is internal to the analyzer; it is not
exposed through the analyzer public API. This is to give us time to
try it out and make changes if necessary before we have to commit to
it.
The advantages of the new API are:
- Better static type checking: with the old API, if we accidentally
forgot to supply arguments to a diagnostic code that required them,
or vice versa, or supplied the wrong number of arguments, the
mistake would not be caught until runtime. If we accidentally
supplied arguments of the wrong type, the mistake would not even be
caught at runtime. With the new API, any of these mistakes will lead
to a compile-time error.
- Better code completion support: with the old API, if we can't
remember whether a diagnostic code requires arguments, we have to
look it up. With the new API, we can type the diagnostic code
followed by `.`, and completions will be offered for either
`.withArguments` (if arguments are required) or
`.withContextMessages` and `.at` (if no arguments are
required). Furthermore, while typing inside the parentheses after
`.withArguments`, completion will offer the names of the required
arguments.
To allow for a gradual transition to the new API, the old API is still
supported. To make this possible, a new sealed class `Reportable` is
introduced, to act as the parameter type for
`DiagnosticReporter.reportError`. It has two derived classes:
- The existing `Diagnostic` class (which was the old parameter type
for `DiagnosticReporter.reportError`)
- A new `LocatedDiagnostic` class (which is the return type of the new
literate `at` method).
The difference between these two classes is that the `Diagnostic`
class has already had its arguments formatted and disambiguated using
`convertTypeNames`, whereas the `LocatedDiagnostic` class hasn't.
The only change to the analyzer public API for now is the introduction
of `Reportable` and the change to the type signature of
`DiagnosticReporter.reportError`. (It would have been hard to avoid
making this public API change, since the method method
`DiagnosticReporter.reportError` is already exposed publically).
To make code review easier, this CL just introduces the necessary
infrastructure to allow a diagnostic code to start supporting the new
literate API, but doesn't make the necessary modifications to any
diagnostic codes to actually support it. In a follow-up CL, I will
flip the flag `literateApiEnabled`, which will change the generated
code and cause the new literate API to be supported.
In follow-up CLs after that, I will transition the analyzer over to
reporting errors using the new API.
Change-Id: I6a6a696478fdd74803c6215c64ec68626819dd95
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/445803
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
Paul Berry
45b0e376f3