Merge pull request #525 from Lysxia/comments

Reword comments about ToJSON and FromJSON

Author: bergmark

Data/Aeson/Types/FromJSON.hs

@@ -281,12 +281,12 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
 --
 -- The basic ways to signal a failed conversion are as follows:
 --
--- * 'empty' and 'mzero' work, but are terse and uninformative
+-- * 'empty' and 'mzero' work, but are terse and uninformative;
 --
--- * 'fail' yields a custom error message
+-- * 'fail' yields a custom error message;
 --
 -- * 'typeMismatch' produces an informative message for cases when the
--- value encountered is not of the expected type
+-- value encountered is not of the expected type.
 --
 -- An example type and instance using 'typeMismatch':
 --
@@ -296,27 +296,27 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
 --
 -- data Coord = Coord { x :: Double, y :: Double }
 --
--- instance FromJSON Coord where
---     parseJSON ('Object' v) = Coord
---         '<$>' v '.:' \"x\" 
+-- instance 'FromJSON' Coord where
+--     'parseJSON' ('Object' v) = Coord
+--         '<$>' v '.:' \"x\"
 --         '<*>' v '.:' \"y\"
 --
 --     \-- We do not expect a non-'Object' value here.
 --     \-- We could use 'mzero' to fail, but 'typeMismatch'
 --     \-- gives a much more informative error message.
---     parseJSON invalid    = 'typeMismatch' \"Coord\" invalid
+--     'parseJSON' invalid    = 'typeMismatch' \"Coord\" invalid
 -- @
 --
 -- For this common case of only being concerned with a single
--- type of JSON value, the functions @withObject@, @withNumber@, etc.
+-- type of JSON value, the functions 'withObject', 'withNumber', etc.
 -- are provided. Their use is to be preferred when possible, since
--- they are more terse. Using @withObject@, we can rewrite the above instance 
+-- they are more terse. Using 'withObject', we can rewrite the above instance
 -- (assuming the same language extension and data type) as:
 --
 -- @
--- instance FromJSON Coord where
---     parseJSON = withObject \"Coord\" $ \v -> Coord
---         '<$>' v '.:' \"x\" 
+-- instance 'FromJSON' Coord where
+--     'parseJSON' = 'withObject' \"Coord\" $ \v -> Coord
+--         '<$>' v '.:' \"x\"
 --         '<*>' v '.:' \"y\"
 -- @
 --
@@ -325,7 +325,7 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
 --
 -- * "Data.Aeson.TH" provides Template Haskell functions which will derive an
 -- instance at compile time. The generated instance is optimized for your type
--- so will probably be more efficient than the following two options:
+-- so it will probably be more efficient than the following option.
 --
 -- * The compiler can provide a default generic implementation for
 -- 'parseJSON'.
@@ -343,18 +343,21 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
 --
 -- data Coord = Coord { x :: Double, y :: Double } deriving 'Generic'
 --
--- instance FromJSON Coord
+-- instance 'FromJSON' Coord
 -- @
 --
--- If @DefaultSignatures@ doesn't give exactly the results you want,
--- you can customize the generic decoding with only a tiny amount of
--- effort, using 'genericParseJSON' with your preferred 'Options':
+-- The default implementation will be equivalent to
+-- @parseJSON = 'genericParseJSON' 'defaultOptions'@; If you need different
+-- options, you can customize the generic decoding by defining:
 --
 -- @
--- instance FromJSON Coord where
---     parseJSON = 'genericParseJSON' 'defaultOptions'
+-- customOptions = 'defaultOptions'
+--                 { 'fieldLabelModifier' = 'map' 'Data.Char.toUpper'
+--                 }
+--
+-- instance 'FromJSON' Coord where
+--     'parseJSON' = 'genericParseJSON' customOptions
 -- @
-
 class FromJSON a where
     parseJSON :: Value -> Parser a
 
@@ -516,7 +519,7 @@ typeMismatch expected actual =
 --
 -- * "Data.Aeson.TH" provides Template Haskell functions which will derive an
 -- instance at compile time. The generated instance is optimized for your type
--- so will probably be more efficient than the following two options:
+-- so it will probably be more efficient than the following option.
 --
 -- * The compiler can provide a default generic implementation for
 -- 'liftParseJSON'.
@@ -534,16 +537,20 @@ typeMismatch expected actual =
 --
 -- data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving 'Generic1'
 --
--- instance FromJSON a => FromJSON1 (Pair a)
+-- instance 'FromJSON' a => 'FromJSON1' (Pair a)
 -- @
 --
--- If @DefaultSignatures@ doesn't give exactly the results you want,
+-- If the default implementation doesn't give exactly the results you want,
 -- you can customize the generic decoding with only a tiny amount of
 -- effort, using 'genericLiftParseJSON' with your preferred 'Options':
 --
 -- @
--- instance FromJSON a => FromJSON1 (Pair a) where
---     liftParseJSON = 'genericLiftParseJSON' 'defaultOptions'
+-- customOptions = 'defaultOptions'
+--                 { 'fieldLabelModifier' = 'map' 'Data.Char.toUpper'
+--                 }
+--
+-- instance 'FromJSON' a => 'FromJSON1' (Pair a) where
+--     'liftParseJSON' = 'genericLiftParseJSON' customOptions
 -- @
 class FromJSON1 f where
     liftParseJSON :: (Value -> Parser a) -> (Value -> Parser [a]) -> Value -> Parser (f a)
@@ -614,43 +621,44 @@ instance (FromJSON a) => FromJSON [a] where
 -- Functions
 -------------------------------------------------------------------------------
 
--- | @withObject expected f value@ applies @f@ to the 'Object' when @value@ is an @Object@
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withObject' expected f value@ applies @f@ to the 'Object' when @value@
+--   is an 'Object' and fails using @'typeMismatch' expected@ otherwise.
 withObject :: String -> (Object -> Parser a) -> Value -> Parser a
 withObject _        f (Object obj) = f obj
 withObject expected _ v            = typeMismatch expected v
 {-# INLINE withObject #-}
 
--- | @withText expected f value@ applies @f@ to the 'Text' when @value@ is a @String@
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withText' expected f value@ applies @f@ to the 'Text' when @value@ is a
+--   'String' and fails using @'typeMismatch' expected@ otherwise.
 withText :: String -> (Text -> Parser a) -> Value -> Parser a
 withText _        f (String txt) = f txt
 withText expected _ v            = typeMismatch expected v
 {-# INLINE withText #-}
 
--- | @withArray expected f value@ applies @f@ to the 'Array' when @value@ is an @Array@
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withArray' expected f value@ applies @f@ to the 'Array' when @value@ is
+-- an 'Array' and fails using @'typeMismatch' expected@ otherwise.
 withArray :: String -> (Array -> Parser a) -> Value -> Parser a
 withArray _        f (Array arr) = f arr
 withArray expected _ v           = typeMismatch expected v
 {-# INLINE withArray #-}
 
--- | @withNumber expected f value@ applies @f@ to the 'Number' when @value@ is a 'Number'.
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withNumber' expected f value@ applies @f@ to the 'Number' when @value@
+-- is a 'Number' and fails using @'typeMismatch' expected@ otherwise.
 withNumber :: String -> (Number -> Parser a) -> Value -> Parser a
 withNumber expected f = withScientific expected (f . scientificToNumber)
 {-# INLINE withNumber #-}
 {-# DEPRECATED withNumber "Use withScientific instead" #-}
 
--- | @withScientific expected f value@ applies @f@ to the 'Scientific' number when @value@ is a 'Number'.
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withScientific' expected f value@ applies @f@ to the 'Scientific' number
+-- when @value@ is a 'Number' and fails using @'typeMismatch' expected@
+-- otherwise.
 withScientific :: String -> (Scientific -> Parser a) -> Value -> Parser a
 withScientific _        f (Number scientific) = f scientific
 withScientific expected _ v                   = typeMismatch expected v
 {-# INLINE withScientific #-}
 
--- | @withBool expected f value@ applies @f@ to the 'Bool' when @value@ is a @Bool@
---   and fails using @'typeMismatch' expected@ otherwise.
+-- | @'withBool' expected f value@ applies @f@ to the 'Bool' when @value@ is a
+-- 'Bool' and fails using @'typeMismatch' expected@ otherwise.
 withBool :: String -> (Bool -> Parser a) -> Value -> Parser a
 withBool _        f (Bool arr) = f arr
 withBool expected _ v          = typeMismatch expected v

Data/Aeson/Types/ToJSON.hs

@@ -205,6 +205,9 @@ genericLiftToEncoding opts te tel = gToEncoding opts (To1Args te tel) . from1
 
 -- | A type that can be converted to JSON.
 --
+-- Instances in general /must/ specify 'toJSON' and /should/ (but don't need
+-- to) specify 'toEncoding'.
+--
 -- An example type and instance:
 --
 -- @
@@ -213,28 +216,26 @@ genericLiftToEncoding opts te tel = gToEncoding opts (To1Args te tel) . from1
 --
 -- data Coord = Coord { x :: Double, y :: Double }
 --
--- instance ToJSON Coord where
---   toJSON (Coord x y) = 'object' [\"x\" '.=' x, \"y\" '.=' y]
+-- instance 'ToJSON' Coord where
+--   'toJSON' (Coord x y) = 'object' [\"x\" '.=' x, \"y\" '.=' y]
 --
---   toEncoding (Coord x y) = 'pairs' (\"x\" '.=' x '<>' \"y\" '.=' y)
+--   'toEncoding' (Coord x y) = 'pairs' (\"x\" '.=' x '<>' \"y\" '.=' y)
 -- @
 --
 -- Instead of manually writing your 'ToJSON' instance, there are two options
 -- to do it automatically:
 --
 -- * "Data.Aeson.TH" provides Template Haskell functions which will derive an
 -- instance at compile time. The generated instance is optimized for your type
--- so will probably be more efficient than the following two options:
+-- so it will probably be more efficient than the following option.
 --
 -- * The compiler can provide a default generic implementation for
 -- 'toJSON'.
 --
 -- To use the second, simply add a @deriving 'Generic'@ clause to your
--- datatype and declare a 'ToJSON' instance for your datatype without giving
--- definitions for 'toJSON' or 'toEncoding'.
---
--- For example, the previous example can be simplified to a more
--- minimal instance:
+-- datatype and declare a 'ToJSON' instance. If you require nothing other than
+-- 'defaultOptions', it is sufficient to write (and this is the only
+-- alternative where the default 'toJSON' implementation is sufficient):
 --
 -- @
 -- {-\# LANGUAGE DeriveGeneric \#-}
@@ -243,30 +244,41 @@ genericLiftToEncoding opts te tel = gToEncoding opts (To1Args te tel) . from1
 --
 -- data Coord = Coord { x :: Double, y :: Double } deriving 'Generic'
 --
--- instance ToJSON Coord where
---     toEncoding = 'genericToEncoding' 'defaultOptions'
+-- instance 'ToJSON' Coord where
+--     'toEncoding' = 'genericToEncoding' 'defaultOptions'
 -- @
 --
--- Why do we provide an implementation for 'toEncoding' here?  The
--- 'toEncoding' function is a relatively new addition to this class.
--- To allow users of older versions of this library to upgrade without
--- having to edit all of their instances or encounter surprising
--- incompatibilities, the default implementation of 'toEncoding' uses
--- 'toJSON'.  This produces correct results, but since it performs an
--- intermediate conversion to a 'Value', it will be less efficient
--- than directly emitting an 'Encoding'.  Our one-liner definition of
--- 'toEncoding' above bypasses the intermediate 'Value'.
---
--- If @DefaultSignatures@ doesn't give exactly the results you want,
--- you can customize the generic encoding with only a tiny amount of
--- effort, using 'genericToJSON' and 'genericToEncoding' with your
--- preferred 'Options':
+-- If on the other hand you wish to customize the generic decoding, you have
+-- to implement both methods:
 --
 -- @
--- instance ToJSON Coord where
---     toJSON     = 'genericToJSON' 'defaultOptions'
---     toEncoding = 'genericToEncoding' 'defaultOptions'
+-- customOptions = 'defaultOptions'
+--                 { 'fieldLabelModifier' = 'map' 'Data.Char.toUpper'
+--                 }
+--
+-- instance 'ToJSON' Coord where
+--     'toJSON'     = 'genericToJSON' customOptions
+--     'toEncoding' = 'genericToEncoding' customOptions
 -- @
+--
+-- Previous versions of this library only had the 'toJSON' method. Adding
+-- 'toEncoding' had to reasons:
+--
+-- 1. toEncoding is more efficient for the common case that the output of
+-- 'toJSON' is directly serialized to a @ByteString@.
+-- Further, expressing either method in terms of the other would be
+-- non-optimal.
+--
+-- 2. The choice of defaults allows a smooth transition for existing users:
+-- Existing instances that do not define 'toEncoding' still
+-- compile and have the correct semantics. This is ensured by making
+-- the default implementation of 'toEncoding' use 'toJSON'. This produces
+-- correct results, but since it performs an intermediate conversion to a
+-- 'Value', it will be less efficient than directly emitting an 'Encoding'.
+-- (this also means that specifying nothing more than
+-- @instance ToJSON Coord@ would be sufficient as a generically decoding
+-- instance, but there probably exists no good reason to not specify
+-- 'toEncoding' in new instances.)
 class ToJSON a where
     -- | Convert a Haskell value to a JSON-friendly intermediate type.
     toJSON     :: a -> Value
@@ -288,8 +300,8 @@ class ToJSON a where
     -- extension, and then have GHC generate a method body as follows.
     --
     -- @
-    -- instance ToJSON Coord where
-    --     toEncoding = 'genericToEncoding' 'defaultOptions'
+    -- instance 'ToJSON' Coord where
+    --     'toEncoding' = 'genericToEncoding' 'defaultOptions'
     -- @
 
     toEncoding :: a -> Encoding
@@ -491,7 +503,7 @@ contramapToJSONKeyFunction h x = case x of
 --
 -- * "Data.Aeson.TH" provides Template Haskell functions which will derive an
 -- instance at compile time. The generated instance is optimized for your type
--- so will probably be more efficient than the following two options:
+-- so it will probably be more efficient than the following option.
 --
 -- * The compiler can provide a default generic implementation for
 -- 'toJSON1'.
@@ -509,19 +521,25 @@ contramapToJSONKeyFunction h x = case x of
 --
 -- data Pair = Pair { pairFst :: a, pairSnd :: b } deriving 'Generic1'
 --
--- instance ToJSON a => ToJSON1 (Pair a)
+-- instance 'ToJSON' a => 'ToJSON1' (Pair a)
 -- @
 --
--- If @DefaultSignatures@ doesn't give exactly the results you want,
+-- If the default implementation doesn't give exactly the results you want,
 -- you can customize the generic encoding with only a tiny amount of
 -- effort, using 'genericLiftToJSON' and 'genericLiftToEncoding' with
 -- your preferred 'Options':
 --
 -- @
--- instance ToJSON a => ToJSON1 (Pair a) where
---     liftToJSON     = 'genericLiftToJSON' 'defaultOptions'
---     liftToEncoding = 'genericLiftToEncoding' 'defaultOptions'
+-- customOptions = 'defaultOptions'
+--                 { 'fieldLabelModifier' = 'map' 'Data.Char.toUpper'
+--                 }
+--
+-- instance 'ToJSON' a => 'ToJSON1' (Pair a) where
+--     'liftToJSON'     = 'genericLiftToJSON' customOptions
+--     'liftToEncoding' = 'genericLiftToEncoding' customOptions
 -- @
+--
+-- See also 'ToJSON'.
 class ToJSON1 f where
     liftToJSON :: (a -> Value) -> ([a] -> Value) -> f a -> Value
 
@@ -588,7 +606,7 @@ toEncoding2 = liftToEncoding2 toEncoding toEncodingList toEncoding toEncodingLis
 -- @
 -- newtype F a = F [a]
 --
--- -- This instance encodes String as an array of chars
+-- -- This instance encodes 'String' as an array of chars
 -- instance 'ToJSON1' F where
 --     'liftToJSON'     tj _ (F xs) = 'liftToJSON'     tj ('listValue'    tj) xs
 --     'liftToEncoding' te _ (F xs) = 'liftToEncoding' te ('listEncoding' te) xs