Reword comments about FromJSON and ToJSON

Lysxia · Lysxia · commit 6b6881574b5b · 2017-03-19T18:01:10.000-04:00
diff --git a/Data/Aeson/Types/FromJSON.hs b/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,
+-- 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 'genericParseJSON' with your preferred 'Options':
 --
 -- @
--- 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)
diff --git a/Data/Aeson/Types/ToJSON.hs b/Data/Aeson/Types/ToJSON.hs
@@ -213,18 +213,18 @@ 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'.
@@ -243,8 +243,8 @@ 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
@@ -257,15 +257,43 @@ genericLiftToEncoding opts te tel = gToEncoding opts (To1Args te tel) . from1
 -- 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,
+-- 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 'genericToJSON' and 'genericToEncoding' with your
--- preferred 'Options':
+-- preferred 'Options'.
+--
+-- The following examples ensure that 'toEncoding' represents the same
+-- encoding as 'toJSON'.
+--
+-- - A typical implementation defines both 'toJSON' and 'toEncoding'
+--   with the same options.
+--
+-- @
+-- customOptions = 'defaultOptions'
+--                 { 'fieldLabelModifier' = 'map' 'Data.Char.toUpper'
+--                 }
+--
+-- instance 'ToJSON' Coord where
+--     'toJSON'     = 'genericToJSON' customOptions
+--     'toEncoding' = 'genericToEncoding' customOptions
+-- @
+--
+-- - A minimal definition of 'ToJSON' is given by 'toJSON'.
+--   This is most useful to define an instance manually when
+--   the generic options are not satisfactory.
+--
+-- @
+-- instance 'ToJSON' Coord where
+--      'toJSON' (Coord x y) = 'Array' (toJSON [x, y])
+-- @
+--
+-- - The default implementation of 'toJSON' uses 'defaultOptions'. If you leave
+--   'toJSON' implicit while providing a more efficient explicit implementation
+--   of 'toEncoding', then it *must* be equivalent to using 'defaultOptions'.
 --
 -- @
 -- instance ToJSON Coord where
---     toJSON     = 'genericToJSON' 'defaultOptions'
---     toEncoding = 'genericToEncoding' 'defaultOptions'
+--     'toEncoding' = 'genericToEncoding' 'defaultOptions'
 -- @
 class ToJSON a where
     -- | Convert a Haskell value to a JSON-friendly intermediate type.
@@ -288,8 +316,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 +519,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 +537,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 +622,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
