Add a TH example.

examples/Generic.hs

@@ -30,7 +30,7 @@ data Coord = Coord { x :: Double, y :: Double }
 instance FromJSON Coord
 instance ToJSON Coord
 
-main ::IO ()
+main :: IO ()
 main = do
   let req = decode "{\"x\":3.0,\"y\":-1.0}" :: Maybe Coord
   print req

examples/GenericSYB.hs

@@ -22,7 +22,7 @@ import qualified Data.ByteString.Lazy.Char8 as BL
 data Coord = Coord { x :: Double, y :: Double }
              deriving (Show, Typeable, Data)
 
-main ::IO ()
+main :: IO ()
 main = do
   let req = decode "{\"x\":3.0,\"y\":-1.0}" :: Maybe Coord
   print req

examples/Simplest.hs

@@ -22,7 +22,7 @@ instance FromJSON Coord where
                          v .: "y"
   parseJSON _          = empty
 
-main ::IO ()
+main :: IO ()
 main = do
   let req = decode "{\"x\":3.0,\"y\":-1.0}" :: Maybe Coord
   print req

examples/TemplateHaskell.hs

@@ -0,0 +1,29 @@
+-- We can use Template Haskell (TH) to generate instances of the
+-- FromJSON and ToJSON classes automatically.  This is the fastest way
+-- to add JSON support for a type.
+
+{-# LANGUAGE TemplateHaskell #-}
+
+{-# LANGUAGE OverloadedStrings #-}
+
+import Data.Aeson (decode, encode)
+import Data.Aeson.TH (deriveJSON)
+import qualified Data.ByteString.Lazy.Char8 as BL
+
+data Coord = Coord { x :: Double, y :: Double }
+             deriving (Show)
+
+-- This splice will derive instances of ToJSON and FromJSON for us.
+--
+-- The use of "id" below is a placeholder function to transform the
+-- names of the type's fields.  We don't want to transform them, so we
+-- use the identity function.
+
+$(deriveJSON id ''Coord)
+
+main :: IO ()
+main = do
+  let req = decode "{\"x\":3.0,\"y\":-1.0}" :: Maybe Coord
+  print req
+  let reply = Coord 123.4 20
+  BL.putStrLn (encode reply)

release-notes.markdown

@@ -1,27 +1,50 @@
 # 0.3 to 0.4
 
+## Ease of use
+
+The new [`decode`
+function](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson.html#v:decode)
+complements the longstanding `encode` function, and makes the API
+simpler.
+
+[New examples](https://github.com/bos/aeson/tree/master/examples) make
+it easier to learn to use the package.
+
+
 ## Generics support
 
-Aeson's support for data-type generic programming makes it possible to
+aeson's support for data-type generic programming makes it possible to
 use JSON encodings of most data types without writing any boilerplate
 instances.
 
 Thanks to Bas Van Dijk, aeson now supports the two major schemes for
 doing datatype-generic programming:
 
-* the newer mechanism, [built into GHC
+* the modern mechanism, [built into GHC
   itself](http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
 
-* the older mechanism, based on SYB (for "scrap your boilerplate")
+* the older mechanism, based on SYB (aka "scrap your boilerplate")
 
-The GHC-based generics are fast and terse: in fact, they're generally
-comparable in performance to hand-written `ToJSON` and `FromJSON`
-instances.  To see how to use GHC generics, see
+The modern GHC-based generic mechanism is fast and terse: in fact, its
+performance is generally comparable in performance to hand-written and
+TH-derived `ToJSON` and `FromJSON` instances.  To see how to use GHC
+generics, refer to
 [`examples/Generic.hs`](https://github.com/bos/aeson/blob/master/examples/Generic.hs).
 
 The SYB-based generics support lives in
-[Data.Aeson.Generic](http://hackage.haskell.org/packages/archive/aeson/0.4.0.0/doc/html/Data-Aeson-Generic.html),
-and is provided mainly for users of GHC older than 7.2.  It's far
+[Data.Aeson.Generic](http://hackage.haskell.org/packages/archive/aeson/latest/doc/html/Data-Aeson-Generic.html),
+and is provided mainly for users of GHC older than 7.2.  SYB is far
 slower (by about 10x) than the more modern generic mechanism.  To see
-how to use SYB generics, see
+how to use SYB generics, refer to
 [`examples/GenericSYB.hs`](https://github.com/bos/aeson/blob/master/examples/GenericSYB.hs).
+
+
+## Improved performance
+
+* We switched the intermediate representation of JSON objects from
+  `Data.Map` to
+  [`Data.HashMap`](http://hackage.haskell.org/package/unordered-containers),
+  which has improved type conversion performance.
+
+* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and
+  70% faster than in 0.3.