Clean up TODOs and comments in Intl

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.
  *
  * For things that require locale or other data, there are multiple different
  * ways of making that data available, which may require importing different
  * libraries. See the class comments for more details.
  *
  * There is also a simple example application that can be found in the
  * `example/basic` directory.
  */
 #library('intl');
 
 #import('src/intl_helpers.dart');
 #import('dart:math');
 #import('date_symbols.dart');
 #import('src/date_format_internal.dart');
 
 #source('date_format.dart');
 #source('src/date_format_field.dart');
 #source('src/date_format_helpers.dart');
 #source('bidi_formatter.dart');
 #source('bidi_utils.dart');
 
+/**
+ * The Intl class provides a common entry point for internationalization
+ * related tasks. An Intl instance can be created for a particular locale

[Emily Fortuna, 2012/10/08 23:16:58]

Does dartdoc distinguish between library and class documentation (aka two
different sections of comments at the top of the file)? I'm not sure it does.

[Alan Knight, 2012/10/08 23:22:50]

It appears to. When I run it as dartdoc.dart intl.dart I get the three paragraph
comment starting with "This library" on docs/intl.html and the message examples
on docs/intl/Intl.html

+ * and used to create a date format via `anIntl.date()`. Static methods
+ * on this class are also used in message formatting.
+ *
+ * _message example:
+ *     '''I see ${Intl.plural(num_people,
+ *               {'0': 'no one at all',
+ *                '1': 'one other person',
+ *                'other': '$num_people other people'})} in $place.''''
+ *
+ * Usage examples:
+ *      today(date) => intl.message(
+ *          "Today's date is $date",
+ *          desc: 'Indicate the current date',
+ *          examples: {'date' : 'June 8, 2012'});
+ *      print(today(new Date.now());
+ *
+ *      msg(num_people, place) => intl.message(
+ *           '''I see ${Intl.plural(num_people,
+ *             {'0': 'no one at all',
+ *              '1': 'one other person',
+ *              'other': '$num_people other people'})} in $place.'''',
+ *          desc: 'Description of how many people are seen as program start.',
+ *          examples: {'num_people': 3, 'place': 'London'});
+ *
+ * Calling `msg({'num_people': 2, 'place': 'Athens'});` would
+ * produce "I see 2 other people in Athens." as output.
+ *
+ * See tests/message_format_test.dart for more examples.
+ */
+ //TODO(efortuna): documentation example involving the offset parameter?
+
 class Intl {
   /**
    * String indicating the locale code with which the message is to be
    * formatted (such as en-CA).
    */
   String _locale;
 
   /** The default locale. This defaults to being set from systemLocale, but
    * can also be set explicitly, and will then apply to any new instances where
    * the locale isn't specified.
    */
   static String _defaultLocale;
 
   /**
    * The system's locale, as obtained from the window.navigator.language
    * or other operating system mechanism. Note that due to system limitations
    * this is not automatically set, and must be set by importing one of
    * intl_browser.dart or intl_standalone.dart and calling findSystemLocale().
    */
-  // TODO(alanknight): Detect this without forcing the jump through hoops.
-  // Issue 5171.
   static String systemLocale = 'en_US';
 
   /**
    * Return a new date format using the specified [pattern].
    * If [desiredLocale] is not specified, then we default to [locale].
    */
   DateFormat date([String pattern, String desiredLocale]) {
     var actualLocale = (desiredLocale == null) ? locale : desiredLocale;
     return new DateFormat(pattern, actualLocale);
   }
@@ skipping 144 matching lines @@
   /**
    * Accessor for the current locale. This should always == the default locale,
    * unless for some reason this gets called inside a message that resets the
    * locale.
    */
   static String getCurrentLocale() {
     if (_defaultLocale == null) _defaultLocale = systemLocale;
     return _defaultLocale;
   }
 }