Bryan O'Sullivan avatar Bryan O'Sullivan committed 640e3e0

Doc improvements.

Comments (0)

Files changed (3)

 
 module Data.Aeson
     (
+    -- * Encoding and decoding
+      decode
+    , encode
     -- * Core JSON types
-      Value(..)
+    , Value(..)
     , Array
     , Object
     -- * Convenience types
     , (.:)
     , (.:?)
     , object
-    -- * Encoding and decoding
-    , decode
-    , encode
     -- * Parsing
     , json
     ) where
 
-import Data.Aeson.Encode
-import Data.Aeson.Parser
+import Data.Aeson.Encode (encode)
+import Data.Aeson.Parser (json)
 import Data.Aeson.Types
 import qualified Data.ByteString.Lazy as L
 import qualified Data.Attoparsec.Lazy as L
 
 -- | Efficiently deserialize a JSON value from a lazy 'L.ByteString'.
+-- If this fails due to incomplete or invalid input, 'Nothing' is
+-- returned.
 decode :: (FromJSON a) => L.ByteString -> Maybe a
 decode s = case L.parse json s of
              L.Done _ v -> case fromJSON v of

Data/Aeson/Types/Internal.hs

 --
 -- An example type and instance:
 --
--- @data Coord { x :: Double, y :: Double }
+-- @{-\# LANGUAGE OverloadedStrings #-}
+--
+-- data Coord { x :: Double, y :: Double }
 --
 -- instance ToJSON Coord where
 --   toJSON (Coord x y) = 'object' [\"x\" '.=' x, \"y\" '.=' y]
 -- @
 --
--- This example assumes the OverloadedStrings language option is enabled.
+-- We use the @OverloadedStrings@ language extension so that we can
+-- write 'Text' values as normal double-quoted strings.
+--
+-- If you do not want to write your own 'ToJSON' instances, you have
+-- two options:
+--
+-- * The 'Data.Aeson.TH' module will automatically derive an instance
+--   for you with a single line of code.
+--
+-- * The 'Data.Aeson.Generic' module will work with most data types
+--   that are instances of 'Data' (but note, this can be slow).
 class ToJSON a where
     toJSON   :: a -> Value
 
 --
 -- An example type and instance:
 --
--- @data Coord { x :: Double, y :: Double }
+-- @{-\# LANGUAGE OverloadedStrings #-}
+--
+-- data Coord { x :: Double, y :: Double }
 -- 
 -- instance FromJSON Coord where
 --   parseJSON ('Object' v) = Coord '<$>'
 --   parseJSON _          = 'mzero'
 -- @
 --
--- This example assumes the OverloadedStrings language option is enabled.
+-- We use the @OverloadedStrings@ language extension so that we can
+-- write 'Text' values as normal double-quoted strings.
+--
+-- If you do not want to write your own 'FromJSON' instances, you have
+-- two options:
+--
+-- * The 'Data.Aeson.TH' module will automatically derive an instance
+--   for you with a single line of code.
+--
+-- * The 'Data.Aeson.Generic' module will work with most data types
+--   that are instances of 'Data' (but note, this can be slow).
 class FromJSON a where
     parseJSON :: Value -> Parser a
 
     A JSON parsing and encoding library optimized for ease of use
     and high performance.
     .
+    To get started, see the documentation for the @Data.Aeson@ module
+    below.
+    .
     /Note/: if you use GHCi or Template Haskell, please see the
     @README@ file for important details about building this package,
     and other packages that depend on it:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.