Add more docs about stack chains to the stack trace package.

pkg/stack_trace/lib/src/chain.dart

 // Copyright (c) 2013, 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.
 
 library stack_trace.chain;
 
 import 'dart:async';
 import 'dart:collection';
 
 import 'frame.dart';
 import 'stack_zone_specification.dart';
 import 'trace.dart';
 import 'utils.dart';
 
 /// A function that handles errors in the zone wrapped by [Chain.capture].
 typedef void ChainHandler(error, Chain chain);
 
 /// A chain of stack traces.
 ///
 /// A stack chain is a collection of one or more stack traces that collectively
 /// represent the path from [main] through nested function calls to a particular
 /// code location, usually where an error was thrown. Multiple stack traces are
 /// necessary when using asynchronous functions, since the program's stack is
 /// reset before each asynchronous callback is run.
 ///
 /// Stack chains can be automatically tracked using [Chain.capture]. This sets
 /// up a new [Zone] in which the current stack chain is tracked and can be
 /// accessed using [new Chain.current]. Any errors that would be top-leveled in
 /// the zone can be handled, along with their associated chains, with the
-/// `onError` callback.
+/// `onError` callback. For example:
+///
+///     Chain.capture(() {
+///       // ...
+///     }, onError: (error, stackChain) {
+///       print("Caught error $error\n"
+///             "$stackChain");
+///     });
 ///
 /// For the most part [Chain.capture] will notice when an error is thrown and
 /// associate the correct stack chain with it; the chain can be accessed using
 /// [new Chain.forTrace]. However, there are some cases where exceptions won't
 /// be automatically detected: any [Future] constructor,
 /// [Completer.completeError], [Stream.addError], and libraries that use these.
 /// For these, all you need to do is wrap the Future or Stream in a call to
 /// [Chain.track] and the errors will be tracked correctly.
 class Chain implements StackTrace {
   /// The line used in the string representation of stack chains to represent
@@ skipping 159 matching lines @@
   }
 
   /// Converts [this] to a [Trace].
   ///
   /// The trace version of a chain is just the concatenation of all the traces
   /// in the chain.
   Trace toTrace() => new Trace(flatten(traces.map((trace) => trace.frames)));
 
   String toString() => traces.join(_GAP);
 }