add useful docs for logging

pkg/logging/lib/logging.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.
 
 /**
- * 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;
 
 import 'dart:async';
 import 'package:unmodifiable_collection/unmodifiable_collection.dart';
 
 /**
  * Whether to allow fine-grain logging and configuration of loggers in a
  * hierarchy. When false, all logging is merged in the root logger.
  */
@@ skipping 287 matching lines @@
   /** Associated stackTrace (if any) when recording errors messages. */
   final StackTrace stackTrace;
 
   LogRecord(this.level, this.message, this.loggerName, [this.error,
                                                         this.stackTrace])
       : time = new DateTime.now(),
         sequenceNumber = LogRecord._nextNumber++;
 
   String toString() => '[${level.name}] $loggerName: $message';
 }