 // Conversions between different Unicode encodings.  Note that UTF-16 and
 // UTF-32 decoding are *not* currently resilient to erroneous data.
 
-public
-enum UnicodeDecodingResult {
+/// The result of one Unicode decoding step
+///
+/// A unicode scalar value, an indication that no more unicode scalars
+/// are available, or an indication of a decoding error.
+public enum UnicodeDecodingResult {
   case Result(UnicodeScalar)
   case EmptyInput
   case Error

  ///
  /// Because of buffering, it is impossible to find the corresponing position
  /// in the generator for a given returned `UnicodeScalar` or an error.
  mutating func decode<
    G : GeneratorType where G.Element == CodeUnit
  >(inout next: G) -> UnicodeDecodingResult

  class func encode<
    S : SinkType where S.Element == CodeUnit
  >(input: UnicodeScalar, inout output: S)

  }
}

/// A Unicode `encoding scheme
/// <http://www.unicode.org/glossary/#character_encoding_scheme>`_
///
/// Consists of an underlying `code unit
/// <http://www.unicode.org/glossary/#code_unit>`_ and functions to
/// translate between sequences of these code units and `unicode
/// scalar values
/// <http://www.unicode.org/glossary/#unicode_scalar_value>`_.
public protocol UnicodeCodecType {

  /// A type that can hold code unit values for this encoding.
  typealias CodeUnit

  init()
