Version 0.8.10.1

dart/pkg/logging/lib/logging.dart

Index: dart/pkg/logging/lib/logging.dart
===================================================================
--- dart/pkg/logging/lib/logging.dart	(revision 29785)
+++ dart/pkg/logging/lib/logging.dart	(working copy)
@@ -3,14 +3,50 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * Support for debugging and error logging.
+ * Support for logging.
  *
- * This library introduces abstractions similar to those used in other
- * languages, such as the Closure JS Logger and java.util.logging.Logger.
- *
  * For information on installing and importing this library, see the
  * [logging package on pub.dartlang.org]
  * (http://pub.dartlang.org/packages/logging).
+ *
+ * ## Initializing
+ *
+ * By default, the logging package does not do anything useful with the
+ * log messages. You must configure the logging level and add a handler
+ * for the log messages.
+ *
+ * Here is a simple logging configuration that logs all messages
+ * via `print`.
+ *
+ *     Logger.root.level = Level.ALL;
+ *     Logger.root.onRecord.listen((LogRecord rec) {
+ *       print('${rec.level.name}: ${rec.time}: ${rec.message}');
+ *     });
+ *
+ * First, set the root [Level]. All messages at or above the level are
+ * sent to the [onRecord] stream.
+ *
+ * Then, listen on the [onRecord] stream for [LogRecord] events. The
+ * [LogRecord] class has various properties for the message, error,
+ * logger name, and more.
+ *
+ * ## Logging messages
+ *
+ * Create a [Logger] with a unique name to easily identify the source
+ * of the log messages.
+ *
+ *     final Logger log = new Logger('MyClassName');
+ *
+ * Here is an example of logging a debug message and an error:
+ *
+ *     Future future = doSomethingAsync();
+ *     future.then((result) {
+ *       log.fine('Got the result: $result');
+ *       processResult(result);
+ *     })
+ *     .catchError((e, stackTrace) => log.severe('Oh noes!', e, stackTrace));
+ *
+ * See the [Logger] class for the different logging methods.
  */
 library logging;