add useful docs for logging

pkg/logging/lib/logging.dart

Index: pkg/logging/lib/logging.dart
diff --git a/pkg/logging/lib/logging.dart b/pkg/logging/lib/logging.dart
index efbe9ba2b8f44ce920e24892574f81d304cc0671..22a4eaec516fa10f520698a462f20c941c8d5ee5 100644
--- a/pkg/logging/lib/logging.dart
+++ b/pkg/logging/lib/logging.dart
@@ -3,14 +3,54 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * Support for debugging and error logging.
- *
- * This library introduces abstractions similar to those used in other
- * languages, such as the Closure JS Logger and java.util.logging.Logger.
+ * Support for logging.
  *
  * 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 logRecord) {
+ *       StringBuffer sb = new StringBuffer()

[kevmoo-old, 2013/11/01 17:49:19]

Maybe use a format string? The StingBuffer is pretty heavy here. Just the logger
and message, maybe?

+ *         ..write(logRecord.time.toString())..write(":")
+ *         ..write(logRecord.loggerName)..write(":")
+ *         ..write(logRecord.level.name)..write(":")
+ *         ..write(logRecord.sequenceNumber)..write(": ")
+ *         ..write(logRecord.message.toString());
+ *       print(sb.toString());
+ *     });
+ *
+ * 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.
+ *
+ * ## 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;