Add docs for new util methods.

lib/src/utils.dart

Index: lib/src/utils.dart
diff --git a/lib/src/utils.dart b/lib/src/utils.dart
index 2f4ff61b7a978770558fa92e422dba3f706013f2..e44e304d7435c43255ffc5d24111fd1cd94f210f 100644
--- a/lib/src/utils.dart
+++ b/lib/src/utils.dart
@@ -323,6 +323,12 @@ Future maybeFirst(Stream stream) {
   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));
@@ -333,6 +339,8 @@ CancelableFuture cancelableNext(StreamQueue queue) {
   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) {