Confusing docs on connectionGetLine

[parsonsmatt]

The docs for connectionGetLine are reproduced here:

-- | Get the next line, using ASCII LF as the line terminator.
--
-- This throws an 'isEOFError' exception on end of input, and LineTooLong when
-- the number of bytes gathered is over the limit without a line terminator.
--
-- The actual line returned can be bigger than the limit specified, provided
-- that the last chunk returned by the underlaying backend contains a LF.
-- In another world only when we need more input and limit is reached that the
-- LineTooLong exception will be raised.
--
-- An end of file will be considered as a line terminator too, if line is
-- not empty.

When I read this initially, I was confused about what happens if the input ends. Reading the source, I see that there's an throwEOF conn loc that is passed to more, but this is never actually called. Instead, the throwEOF invocation that could happen here happens from connectionGetChunkBase, which occurs when the connectionBuffer conn MVar value is a Nothing. The comment on that field says:

    , connectionBuffer  :: MVar (Maybe ByteString) -- ^ this is set to 'Nothing' on EOF

If that's Just, then we check if it is empty. If it is, then we try to get more data. If it's still empty after getting more data, we close the connection and return f applied to the empty bytestring. If it's got more data, then you update the buffer with the remainder.

So, as far as I can tell:

• If Connection is already done (eg hit EOF), then connectionGetLine throws an EOF error.
• If Connection encounters an EOF condition (no more bytes from upstream, even after requesting more) then it returns the ByteString as if it found a \n and closes the MVar.
• If Connection encounters a \n it returns the bytestring accumulated so far.
• If Connection gets too many bytes then it throws the line error.

I'll try to come up with a patch to make the docs easier to understand and maybe remove the unused throwEOF parameter to more.