[analyzer] Fix messages.yaml parameter documentation.
Fixes the documentatino in messages.yaml to account for the fact that:
- A `parameters:` entry is now required.
- At the time an error is reported, arguments can be supplied using a
`withArguments` method. This approach allows for compile-time
checking of the type and number of arguments.
Change-Id: I6a6a69649e765d9894bb78456f53506c0570e1e6
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/448238
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
diff --git a/pkg/analyzer/messages.yaml b/pkg/analyzer/messages.yaml
index a2844a6..f218795 100644
--- a/pkg/analyzer/messages.yaml
+++ b/pkg/analyzer/messages.yaml
@@ -44,16 +44,21 @@
# parameter. Placeholders in the `problemMessage` and `correctionMessage`
# strings take the form `#NAME`.
#
-# If a diagnostic takes no parameters, it should have an entry of the
+# If a diagnostic takes no parameters, it must have an entry of the
# form `parameters: none`.
#
-# At the time the analyzer reports the error, it supplies
-# substitutions to take the place of the `#NAME` placeholders in the
-# form of a list whose order matches the order of the key/value pairs
-# in the `parameters` map. In the future, a new mechanism will be
-# introduced to allow the substitutions to be supplied using named
-# arguments, and statically type checked using the specified
-# TYPEs. For now, the TYPEs are unused.
+# Errors can be reported in two ways:
+#
+# - The old way (deprecated): at the time the analyzer reports the
+# error, it supplies substitutions to take the place of the `#NAME`
+# placeholders in the form of a list whose order matches the order
+# of the key/value pairs in the `parameters` map. The number and
+# types of the supplied values are checked at runtime.
+#
+# - The new way: at the time the analyzer reports the error, it calls
+# the error code's `withArguments` method, supplying the
+# substitutions in the form of named parameters. The number and
+# types of the supplied values are checked at compile time.
AnalysisOptionsErrorCode:
INCLUDED_FILE_PARSE_ERROR:
