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

pkg/intl/lib/intl.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * This library provides internationalization and localization. This includes
  * message formatting and replacement, date and number formatting and parsing,
  * and utilities for working with Bidirectional text.
  *
  * This is part of the [intl package]
@@ skipping 111 matching lines @@
    */
   Intl([String aLocale]) {
     if (aLocale != null) {
       _locale = aLocale;
     } else {
       _locale = getCurrentLocale();
     }
   }
 
   /**
-   * 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,
       List<String> args}) {
     return messageLookup.lookupMessage(
         message_str, desc, examples, locale, name, args);
   }
 
   /**
    * Return the locale for this instance. If none was set, the locale will
@@ skipping 194 matching lines @@
    * unless for some reason this gets called inside a message that resets the
    * locale.
    */
   static String getCurrentLocale() {
     if (defaultLocale == null) defaultLocale = systemLocale;
     return defaultLocale;
   }
 
   toString() => "Intl($locale)";
 }