hGet documentation on return type is incorrect

[robinp]

Hello,

See

bytestring/Data/ByteString.hs

Line 1927 in 6641404

hGet :: Handle -> Int -> IO ByteString

. It states it returns the bytes read, up to n. But that is the behavior of the underlying hGetBuf, not hGet. hGet itself returns a ByteString with length up to n.

I think it would also be ergonomic to call out with emphasis that near EOF the returned bytestring can be shorter. (On a quick skimming, I assumed that hGet would fail / return empty if not enough bytes are available, while hGetSome would return the partial bytes. But turns out the difference is rather in terms of blocking or not in case data is not yet available?)

Also the doc Like hGet, except that a shorter ByteStringmay be returned if there are not enough bytes immediately available to satisfy the whole request. on hGetSome adds to the confusion. Kind of implies to the unaware reader that hGet would always return non-shorter bytestring.

[Bodigrim]

But turns out the difference is rather in terms of blocking or not in case data is not yet available?

Correct. It all follows the behaviour of https://hackage.haskell.org/package/base-4.18.0.0/docs/System-IO.html#v:hGetBuf and below.

Feel free to raise a PR improving documentation.