@@ -172,11 +172,15 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
172172-- a 'ByteString' that represents a possibly incomplete input (e.g. a
173173-- packet from a network stream) that may not end on a UTF-8 boundary.
174174--
175−-- The first element of the result is the maximal chunk of 'Text' that
176−-- can be decoded from the given input. The second is a function which
177−-- accepts another 'ByteString'. That string will be assumed to
178−-- directly follow the string that was passed as input to the original
179−-- function, and it will in turn be decoded.
175+-- 1. The maximal prefix of 'Text' that could be decoded from the
176+-- given input.
177+--
178+-- 2. The suffix of the 'ByteString' that could not be decoded due to
179+-- insufficient input.
180+--
181+-- 3. A function that accepts another 'ByteString'. That string will
182+-- be assumed to directly follow the string that was passed as
183+-- input to the original function, and it will in turn be decoded.
180184--
181185-- To help understand the use of these functions, consider the Unicode
182186-- string @\"hi ☃\"@. If encoded as UTF-8, this becomes @\"hi
@@ -189,15 +193,17 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
189193-- as we receive each one.
190194--
191195-- @
192−-- let 'Some' t0 f0 = 'streamDecodeUtf8' \"hi \\xe2\"
193−-- t0 == \"hi \" :: 'Text'
196+-- ghci> let s0\@('Some' _ _ f0) = 'streamDecodeUtf8' \"hi \\xe2\"
197+-- ghci> s0
198+-- 'Some' \"hi \" \"\\xe2\" _
194199-- @
195200--
196201-- We use the continuation @f0@ to decode our second packet.
197202--
198203-- @
199−-- let 'Some' t1 f1 = f0 \"\\x98\"
200−-- t1 == \"\"
204+-- ghci> let s1\@('Some' _ _ f1) = f0 \"\\x98\"
205+-- ghci> s1
206+-- 'Some' \"\" \"\\xe2\\x98\"
201207-- @
202208--
203209-- We could not give @f0@ enough input to decode anything, so it
@@ -205,8 +211,9 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
205211-- the last byte of input, it will make progress.
206212--
207213-- @
208−-- let 'Some' t2 f2 = f1 \"\\x83\"
209−-- t2 == \"☃\"
214+-- ghci> let s2\@('Some' _ _ f2) = f1 \"\\x83\"
215+-- ghci> s2
216+-- 'Some' \"\\x2603\" \"\" _
210217-- @
211218--
212219-- If given invalid input, an exception will be thrown by the function