@@ -76,7 +76,8 @@ module Data.Aeson
7676 ) where
7777
7878import Data.Aeson.Encode (encode)
79−import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, jsonEOF, json, jsonEOF', json')
79+import Data.Aeson.Parser.Internal (decodeWith, eitherDecodeWith, jsonEOF, json,
80+ jsonEOF', json')
8081import Data.Aeson.Types
8182import qualified Data.ByteString.Lazy as L
8283
@@ -84,6 +85,12 @@ import qualified Data.ByteString.Lazy as L
8485-- If this fails due to incomplete or invalid input, 'Nothing' is
8586-- returned.
8687--
88+-- The input must consist solely of a JSON document, with no trailing
89+-- data except for whitespace. This restriction is necessary to ensure
90+-- that if data is being lazily read from a file handle, the file
91+-- handle will be closed in a timely fashion once the document has
92+-- been parsed.
93+--
8794-- This function parses immediately, but defers conversion. See
8895-- 'json' for details.
8996decode :: (FromJSON a) => L.ByteString -> Maybe a
@@ -94,6 +101,12 @@ decode = decodeWith jsonEOF fromJSON
94101-- If this fails due to incomplete or invalid input, 'Nothing' is
95102-- returned.
96103--
104+-- The input must consist solely of a JSON document, with no trailing
105+-- data except for whitespace. This restriction is necessary to ensure
106+-- that if data is being lazily read from a file handle, the file
107+-- handle will be closed in a timely fashion once the document has
108+-- been parsed.
109+--
97110-- This function parses and performs conversion immediately. See
98111-- 'json'' for details.
99112decode' :: (FromJSON a) => L.ByteString -> Maybe a