     return 1
   }
 
+  /// Start or continue decoding a UTF sequence.
+  ///
+  /// In order to decode a code unit sequence completely, this function should
+  /// be called repeatedly until it returns `UnicodeDecodingResult.EmptyInput`.
+  /// Checking that the generator was exhausted is not sufficient.  The decoder
+  /// can have an internal buffer that is pre-filled with data from the input
+  /// generator.
+  ///
+  /// Because of buffering, it is impossible to find the corresponing position
+  /// in the generator for a given returned `UnicodeScalar` or an error.
+  ///
+  /// :param: `next`: a *generator* of code units to be decoded.
   public mutating func decode<
     G : GeneratorType where G.Element == CodeUnit
   >(inout next: G) -> UnicodeDecodingResult {

}

public struct UTF16 : UnicodeCodecType {
  public typealias CodeUnit = UInt16

  public init() {}

  /// `x` is set when `_decodeLookahead` contains a code unit.
  var _lookaheadFlags: UInt8 = 0

  /// Start or continue decoding a UTF sequence.
  ///
  /// In order to decode a code unit sequence completely, this function should
  /// be called repeatedly until it returns `UnicodeDecodingResult.EmptyInput`.
  /// Checking that the generator was exhausted is not sufficient.  The decoder
  /// can have an internal buffer that is pre-filled with data from the input
  /// generator.
  ///
  /// Because of buffering, it is impossible to find the corresponing position
  /// in the generator for a given returned `UnicodeScalar` or an error.
  ///
  /// :param: `next`: a *generator* of code units to be decoded.
  public mutating func decode<
    G : GeneratorType where G.Element == CodeUnit
  >(inout input: G) -> UnicodeDecodingResult {
