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

  return (nextIndex, result)
}

internal protocol _StringElementType {
  class func _toUTF16CodeUnit(_: Self) -> UTF16.CodeUnit
  class func _fromUTF16CodeUnit(utf16: UTF16.CodeUnit) -> Self

  ///
  /// 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.
  mutating func decode<
    G : GeneratorType where G.Element == CodeUnit
  >(inout next: G) -> UnicodeDecodingResult

  /// Encode a `UnicodeScalar` as a series of `CodeUnit`\ s by `put`\
  /// 'ing each `CodeUnit` to `output`.
  class func encode<
    S : SinkType where S.Element == CodeUnit
  >(input: UnicodeScalar, inout output: S)
