Read Intl.message examples argument as a map, not a string

pkg/intl/lib/intl.dart

Index: pkg/intl/lib/intl.dart
diff --git a/pkg/intl/lib/intl.dart b/pkg/intl/lib/intl.dart
index 7fff85070a5e425ddea71852a0fac0165fd33194..200b1569aab4846e5e6c4220d8a64ced14449e6c 100644
--- a/pkg/intl/lib/intl.dart
+++ b/pkg/intl/lib/intl.dart
@@ -129,22 +129,35 @@ class Intl {
   }
 
   /**
-   * Returns a message that can be internationalized. It takes a
-   * [message_str] that will be translated, which may be interpolated
+   * Returns a message that can be internationalized. It is expected

[Emily Fortuna, 2014/01/10 01:40:56]

while you're changing this comment, let's make it follow the "comment style
guide". First sentence should be its own "paragraph" and then separate a newline
and then the other sentences.

+   * to be used inside an enclosing function that just returns its value
+   * and provides a scope for the variables to be substituted in the
+   * message. The parameters are a
+   * [message_str] to be translated, which may be interpolated
    * based on one or more variables, a [desc] providing a description of usage
-   * for the [message_str], and a map of [examples] for each data element to be
-   * substituted into the message. For example, if message="Hello, $name", then
-   * examples = {'name': 'Sparky'}. If not using the user's default locale, or
-   * if the locale is not easily detectable, explicitly pass [locale].
-   * The values of [desc] and [examples] are not used at run-time but are only
-   * made available to the translators, so they MUST be simple Strings available
-   * at compile time: no String interpolation or concatenation.
+   * and a map of [examples] for each interpolated variable. For example
+   *       hello(yourName) => Intl.message("Hello, $yourName",
+   *         name: "hello",
+   *         args: [name],
+   *         desc: "Say hello",
+   *         examples = {"yourName": "Sparky"}.
+   * The source code will be processed via the analyzer to extract out the
+   * message data, so only a subset of valid Dart code is accepted. In
+   * particular, everything must be literal and cannot refer to variables
+   * outside the scope of the enclosing function. The [examples] map must
+   * be valid JSON, which in addition to requiring only simple literals means
+   * that strings must use double-quotes exclusively and cannot use features
+   * like raw strings or concatenation. Similarly, the [desc] argument must
+   * be a single, simple string.
+   *
    * The expected usage of this is inside a function that takes as parameters
-   * the variables used in the interpolated string, and additionally also a
-   * locale (optional).
-   * Ultimately, the information about the enclosing function and its arguments
-   * will be extracted automatically but for the time being it must be passed
-   * explicitly in the [name] and [args] arguments.
+   * the variables used in the interpolated string, and an optional
+   * locale.
+   *
+   * The [name] and [args] arguments are required, and are used at runtime
+   * to look up the localized version and pass the appropriate arguments to it.
+   * We may in the future modify the code during compilation to make manually
+   * passing those arguments unnecessary.
    */
   static String message(String message_str, {final String desc: '',
       final Map examples: const {}, String locale, String name,