   /// `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 {

}

public struct UTF16 : UnicodeCodecType {
  public typealias CodeUnit = UInt16

  public init() {}

/// <http://www.unicode.org/glossary/#unicode_scalar_value>`_.
public protocol UnicodeCodecType {

  /// A type that can hold `code unit
  /// <http://www.unicode.org/glossary/#code_unit>`_ values for this
  /// encoding.
  typealias CodeUnit

  init()
