   }
 }
 
+/// 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()

// Conversions between different Unicode encodings.  Note that UTF-16 and
// UTF-32 decoding are *not* currently resilient to erroneous data.

public
enum UnicodeDecodingResult {
  case Result(UnicodeScalar)
  case EmptyInput
  case Error

  return (nextIndex, result)
}

/// Instances of conforming types are used in internal `String`
/// representation.
internal protocol _StringElementType {
  class func _toUTF16CodeUnit(_: Self) -> UTF16.CodeUnit
  class func _fromUTF16CodeUnit(utf16: UTF16.CodeUnit) -> Self
