Revert "Revert "Fix dartdoc block code comments in Dart API that are broken and use [: :] delimiter…

runtime/bin/input_stream.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.
 
 /**
  * Basic input stream which supplies binary data.
  *
  * Input streams are used to read data sequentially from some data
  * source. All input streams are non-blocking. They each have a number
  * of read calls which will always return without any IO related
  * blocking. If the requested data is not available a read call will
- * return [:null:]. All input streams have one or more handlers which
+ * return `null`. All input streams have one or more handlers which
  * will trigger when data is available.
  *
  * The following example shows a data handler in an ordinary input
  * stream which will be called when some data is available and a call
- * to read will not return [:null:].
+ * to read will not return `null`.
  *
- * [:
- *    InputStream input = ...
- *    input.onData = () {
- *      var data = input.read();
- *      ...
- *    };
- * :]
+ *     InputStream input = ...
+ *     input.onData = () {
+ *       var data = input.read();
+ *       ...
+ *     };
  *
  * If for some reason the data from an input stream cannot be handled
- * by the application immediately setting the data handler to [:null:]
+ * by the application immediately setting the data handler to `null`
  * will avoid further callbacks until it is set to a function
  * again. While the data handler is not active system flow control
  * will be used to avoid buffering more data than needed.
  *
  * Always set up appropriate handlers when using input streams.
  *
  */
 interface InputStream {
   /**
    * Reads data from the stream. Returns a system allocated buffer
@@ skipping 13 matching lines @@
 
   /**
    * Returns the number of bytes available for immediate reading.
    */
   int available();
 
   /**
    * Pipe the content of this input stream directly to the output
    * stream [output]. The default behavior is to close the output when
    * all the data from the input stream have been written. Specifying
-   * [:false:] for the optional argument [close] keeps the output
+   * `false` for the optional argument [close] keeps the output
    * stream open after writing all data from the input stream. The
-   * default value for [close] is [:true:].
+   * default value for [close] is `true`.
    */
   void pipe(OutputStream output, [bool close]);
 
   /**
    * Close the underlying communication channel to avoid getting any
    * more data. In normal situations, where all data is read from the
    * stream until the close handler is called, calling [close] is not
    * required. When [close] is used the close handler will still be
    * called.
    */
@@ skipping 37 matching lines @@
 
 
 /**
  * A string input stream wraps a basic input stream and supplies
  * string data. This data can be read either as string chunks or as
  * lines separated by line termination character sequences.
  */
 interface StringInputStream default _StringInputStream {
   /**
    * Decodes a binary input stream into characters using the specified
-   * encoding. The default encoding is UTF-8 - [:Encoding.UTF_8:].
+   * encoding. The default encoding is UTF-8 - `Encoding.UTF_8`.
    */
   StringInputStream(InputStream input, [Encoding encoding]);
 
   /**
    * Reads as many characters as is available from the stream. If no data is
    * available null will be returned.
    */
   String read();
 
   /**
@@ skipping 106 matching lines @@
   void set onError(void callback(e));
 }
 
 
 class StreamException implements Exception {
   const StreamException([String this.message = ""]);
   const StreamException.streamClosed() : message = "Stream closed";
   String toString() => "StreamException: $message";
   final String message;
 }