X-Git-Url: http://git.megacz.com/?p=ghc-base.git;a=blobdiff_plain;f=GHC%2FIO%2FEncoding%2FTypes.hs;h=ebce578219061f71f64f9c23f869ef327ec82d86;hp=706f7b539c08c1eada79113093b573f1ce38be18;hb=4c889c7daa98daff7aec5c0e4ccf491f25f5d10c;hpb=509f28cc93b980d30aca37008cbe66c677a0d6f6

diff --git a/GHC/IO/Encoding/Types.hs b/GHC/IO/Encoding/Types.hs
index 706f7b5..ebce578 100644
--- a/GHC/IO/Encoding/Types.hs
+++ b/GHC/IO/Encoding/Types.hs
@@ -43,6 +43,14 @@ data BufferCodec from to state = BufferCodec {
    -- The fact that as many elements as possible are translated is used by the IO
    -- library in order to report translation errors at the point they
    -- actually occur, rather than when the buffer is translated.
+   --
+   -- To allow us to use iconv as a BufferCode efficiently, character buffers are
+   -- defined to contain lone surrogates instead of those private use characters that
+   -- are used for roundtripping. Thus, Chars poked and peeked from a character buffer
+   -- must undergo surrogatifyRoundtripCharacter and desurrogatifyRoundtripCharacter
+   -- respectively.
+   --
+   -- For more information on this, see Note [Roundtripping] in GHC.IO.Encoding.Failure.
   
   recover :: Buffer from -> Buffer to -> IO (Buffer from, Buffer to),
    -- ^ The @recover@ function is used to continue decoding
@@ -56,6 +64,9 @@ data BufferCodec from to state = BufferCodec {
    -- of free space.
    --
    -- @recover@ may raise an exception rather than skipping anything.
+   --
+   -- Currently, some implementations of @recover@ may mutate the input buffer.
+   -- In particular, this feature is used to implement transliteration.
   
   close  :: IO (),
    -- ^ Resources associated with the encoding may now be released.