Improve documentation for utf8 decoder (and BOMs).

sdk/lib/convert/utf.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.convert;
 
 /** The Unicode Replacement character `U+FFFD` (�). */
 const int UNICODE_REPLACEMENT_CHARACTER_RUNE = 0xFFFD;
 
 /** The Unicode Byte Order Marker (BOM) character `U+FEFF`. */
@@ skipping 312 matching lines @@
   const Utf8Decoder({ bool allowMalformed: false })
       : this._allowMalformed = allowMalformed;
 
   /**
    * Converts the UTF-8 [codeUnits] (a list of unsigned 8-bit integers) to the
    * corresponding string.
    *
    * Uses the code units from [start] to, but no including, [end].
    * If [end] is omitted, it defaults to `codeUnits.length`.
    *
-   * If the [codeUnits] start with a leading [UNICODE_BOM_CHARACTER_RUNE] this
-   * character is discarded.
+   * If the [codeUnits] start with the encoding of a
+   * [UNICODE_BOM_CHARACTER_RUNE], that character is discarded.
    */
   String convert(List<int> codeUnits, [int start = 0, int end]) {
     // Allow the implementation to intercept and specialize based on the type
     // of codeUnits.
     String result = _convertIntercepted(_allowMalformed, codeUnits, start, end);
     if (result != null) {
       return result;
     }
 
     int length = codeUnits.length;
@@ skipping 229 matching lines @@
       }
       break loop;
     }
     if (expectedUnits > 0) {
       _value = value;
       _expectedUnits = expectedUnits;
       _extraUnits = extraUnits;
     }
   }
 }