Documentation improvements

Author: Bodigrim

Data/ByteString.hs

@@ -1558,6 +1558,13 @@ isValidUtf8 (BS ptr len) = accursedUnutterablePerformIO $ unsafeWithForeignPtr p
 
 -- | Break a string on a substring, returning a pair of the part of the
 -- string prior to the match, and the rest of the string.
+-- If the substring is not found, return the entire string in the first component
+-- and an empty string in the second component.
+--
+-- >>> breakSubstring "needle" "hayneedlestraw"
+-- ("hay","needlestraw")
+-- >>> breakSubstring "needle" "hay"
+-- ("hay","")
 --
 -- The following relationships hold:
 --
@@ -1576,7 +1583,7 @@ isValidUtf8 (BS ptr len) = accursedUnutterablePerformIO $ unsafeWithForeignPtr p
 --
 -- > fst (breakSubstring x y)
 --
--- Note that calling `breakSubstring x` does some preprocessing work, so
+-- Note that calling 'breakSubstring' @x@ does some preprocessing work, so
 -- you should avoid unnecessarily duplicating breakSubstring calls with the same
 -- pattern.
 --
@@ -2017,8 +2024,7 @@ hGetContentsSizeHint hnd =
              -- we grow the buffer sizes, but not too huge
              -- we concatenate in the end anyway
 
--- | getContents. Read stdin strictly. Equivalent to hGetContents stdin
--- The 'Handle' is closed after the contents have been read.
+-- | Equivalent to 'hGetContents' 'stdin', reading it /strictly/.
 --
 getContents :: IO ByteString
 getContents = hGetContents stdin

Data/ByteString/Lazy.hs

@@ -1597,11 +1597,21 @@ illegalBufferSize handle fn sz =
       msg = fn ++ ": illegal ByteString size " ++ showsPrec 9 sz []
 
 -- | Read entire handle contents /lazily/ into a 'ByteString'. Chunks
--- are read on demand, using the default chunk size.
+-- are read on demand, using the default chunk size ('defaultChunkSize').
 --
 -- File handles are closed on EOF if all the file is read, or through
 -- garbage collection otherwise.
 --
+-- Do not use this function inside a 'Control.Exception.bracket' \/
+-- 'System.IO.withFile' \/ 'System.IO.withBinaryFile':
+-- lazy I/O will escape it causing 'Control.Exception.bracket' to close a handle prematurely:
+--
+-- >>> withBinaryFile "foo.txt" ReadMode BL.hGetContents >>= print
+-- "*** Exception: foo.txt: hGetBufSome: illegal operation (handle is closed)
+--
+-- Consider using 'readFile' instead; if you must use 'hGetContents' then open a handle,
+-- pass it to 'hGetContents' and leave it to close the handle when it sees fit.
+--
 hGetContents :: Handle -> IO ByteString
 hGetContents = hGetContentsN defaultChunkSize
 
@@ -1644,7 +1654,7 @@ writeFile = modifyFile WriteMode
 appendFile :: FilePath -> ByteString -> IO ()
 appendFile = modifyFile AppendMode
 
--- | getContents. Equivalent to hGetContents stdin. Will read /lazily/
+-- | Equivalent to 'hGetContents' 'stdin', reading it /lazily/.
 --
 getContents :: IO ByteString
 getContents = hGetContents stdin

Data/ByteString/Lazy/Internal.hs

@@ -78,9 +78,14 @@ import Control.Exception (assert)
 -- 8-bit characters.
 --
 #ifndef HS_BYTESTRING_ASSERTIONS
-data ByteString = Empty | Chunk  {-# UNPACK #-} !S.StrictByteString ByteString
-  -- INVARIANT: The S.StrictByteString field of any Chunk is not empty.
-  -- (See also the 'invariant' and 'checkInvariant' functions.)
+data ByteString
+  = Empty
+  | Chunk
+    {-# UNPACK #-} !S.StrictByteString
+    -- ^ Must be nonempty. Consider using
+    -- a smart constructor 'chunk' to ensure this invariant.
+    -- See also the 'invariant' and 'checkInvariant' functions.
+    LazyByteString
 
   -- To make testing of this invariant convenient, we add an
   -- assertion to that effect when the HS_BYTESTRING_ASSERTIONS

Data/ByteString/Short/Internal.hs

@@ -1296,6 +1296,13 @@ isSuffixOf sbs1 = \sbs2 -> do
 
 -- | Break a string on a substring, returning a pair of the part of the
 -- string prior to the match, and the rest of the string.
+-- If the substring is not found, return the entire string in the first component
+-- and an empty string in the second component.
+--
+-- >>> breakSubstring "needle" "hayneedlestraw"
+-- ("hay","needlestraw")
+-- >>> breakSubstring "needle" "hay"
+-- ("hay","")
 --
 -- The following relationships hold:
 --