Commits

Bryan O'Sullivan  committed 86798c5

Clarify decode docs

  • Participants
  • Parent commits 0b1ed04

Comments (0)

Files changed (1)

File Data/Aeson.hs

     ) where
 
 import Data.Aeson.Encode (encode)
-import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, jsonEOF, json, jsonEOF', json')
+import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, jsonEOF, json,
+                                   jsonEOF', json')
 import Data.Aeson.Types
 import qualified Data.ByteString.Lazy as L
 
 -- If this fails due to incomplete or invalid input, 'Nothing' is
 -- returned.
 --
+-- The input must consist solely of a JSON document, with no trailing
+-- data except for whitespace. This restriction is necessary to ensure
+-- that if data is being lazily read from a file handle, the file
+-- handle will be closed in a timely fashion once the document has
+-- been parsed.
+--
 -- This function parses immediately, but defers conversion.  See
 -- 'json' for details.
 decode :: (FromJSON a) => L.ByteString -> Maybe a
 -- If this fails due to incomplete or invalid input, 'Nothing' is
 -- returned.
 --
+-- The input must consist solely of a JSON document, with no trailing
+-- data except for whitespace. This restriction is necessary to ensure
+-- that if data is being lazily read from a file handle, the file
+-- handle will be closed in a timely fashion once the document has
+-- been parsed.
+--
 -- This function parses and performs conversion immediately.  See
 -- 'json'' for details.
 decode' :: (FromJSON a) => L.ByteString -> Maybe a