Add docs for new util methods.

lib/src/utils.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 test.utils;
 
 import 'dart:async';
 import 'dart:convert';
 import 'dart:math' as math;
 
@@ skipping 305 matching lines @@
   }, onError: (error, stackTrace) {
     completer.completeError(error, stackTrace);
     subscription.cancel();
   }, onDone: () {
     completer.complete();
   });
 
   return completer.future;
 }
 
+/// Returns a [CancelableFuture] that returns the next value of [queue] unless
+/// it's canceled.
+///
+/// If the future is canceled, [queue] is not moved forward at all. Note that
+/// it's not safe to call further methods on [queue] until this future has
+/// either completed or been canceled.
 CancelableFuture cancelableNext(StreamQueue queue) {
   var fork = queue.fork();
   var completer = new CancelableCompleter(() => fork.cancel(immediate: true));
   completer.complete(fork.next.then((_) {
     fork.cancel();
     return queue.next;
   }));
   return completer.future;
 }
 
+/// Returns the result of whichever of [futures] completes first, and cancels
+/// the others.
 Future race(Iterable<CancelableFuture> futures) {
   var completer = new Completer.sync();
   for (var future in futures) {
     future.then((value) {
       if (!completer.isCompleted) completer.complete(value);
     }).catchError((error, stackTrace) {
       if (!completer.isCompleted) completer.completeError(error, stackTrace);
     });
   }
 
@@ skipping 73 matching lines @@
   }
 }
 
 /// Returns middleware that nests all requests beneath the URL prefix [beneath].
 shelf.Middleware nestingMiddleware(String beneath) {
   return (handler) {
     var pathHandler = new PathHandler()..add(beneath, handler);
     return pathHandler.handler;
   };
 }