Warn when adding something to a closed sink and improve documentation

sdk/lib/io/io_sink.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.
 
 part of dart.io;
 
 /**
  * A combined byte and text output.
  *
  * An [IOSink] combines a [StreamSink] of bytes with a [StringSink],
  * and allows easy output of both bytes and text.
  *
  * Writing text ([write]) and adding bytes ([add]) may be interleaved freely.
  *
  * While a stream is being added using [addStream], any further attempts
  * to add or write to the [IOSink] will fail until the [addStream] completes.
  *
- * If data is added to the [IOSink] after the sink is closed, the data will be
- * ignored. Use the [done] future to be notified when the [IOSink] is closed.
+ * It is an error to add data to the [IOSink] after the sink is closed.
  */
 abstract class IOSink implements StreamSink<List<int>>, StringSink {
   /**
    * Create an [IOSink] that outputs to a [target] [StreamConsumer] of bytes.
    *
    * Text written to [StreamSink] methods is encoded to bytes using [encoding]
    * before being output on [target].
    */
   factory IOSink(StreamConsumer<List<int>> target, {Encoding encoding: UTF8}) =>
       new _IOSinkImpl(target, encoding);
@@ skipping 110 matching lines @@
   final StreamConsumer<T> _target;
   final Completer _doneCompleter = new Completer();
   StreamController<T> _controllerInstance;
   Completer _controllerCompleter;
   bool _isClosed = false;
   bool _isBound = false;
   bool _hasError = false;
 
   _StreamSinkImpl(this._target);
 
+  void _reportClosedSink() {
+    // TODO(29554): this is very brittle and depends on the layout of the
+    // stderr class.
+    if (this == stderr._sink) {
+      // We can't report on stderr anymore (as we would otherwise
+      // have an infinite recursion.
+      throw new StateError("Stderr is closed.");
+    }
+    // TODO(29554): throw a StateError, and don't just report the problem.
+    stderr.writeln("StreamSink is closed and adding to it is an error.");
+    stderr.writeln("  See http://dartbug.com/29554.");
+    stderr.writeln(StackTrace.current);
+  }
+
   void add(T data) {
-    if (_isClosed) return;
+    if (_isClosed) {
+      _reportClosedSink();
+      return;
+    }
     _controller.add(data);
   }
 
   void addError(error, [StackTrace stackTrace]) {
+    if (_isClosed) {
+      _reportClosedSink();
+      return;
+    }
     _controller.addError(error, stackTrace);
   }
 
   Future addStream(Stream<T> stream) {
     if (_isBound) {
       throw new StateError("StreamSink is already bound to a stream");
     }
     _isBound = true;
     if (_hasError) return done;
     // Wait for any sync operations to complete.
@@ skipping 134 matching lines @@
 
   void writeln([Object object = ""]) {
     write(object);
     write("\n");
   }
 
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
 }