[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 <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

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: