Add an example and generally improve docs

Data/Ceason.hs

@@ -11,7 +11,11 @@
 --    need to be escaped).
 module Data.Ceason
     (
+    -- * Usage example
+    -- $example
+
     -- * Encoding and decoding
+    -- $encoding
       decode
     , decodeByName
     , encode
@@ -42,6 +46,7 @@ module Data.Ceason
     -- ** Index-based record conversion
     -- $indexbased
     , FromRecord(..)
+    , Parser
     , (.!)
     , ToRecord(..)
     , record
@@ -66,6 +71,35 @@ import Data.Ceason.Conversion
 import Data.Ceason.Encoding
 import Data.Ceason.Types
 
+-- $example
+--
+-- A short encoding usage example:
+--
+-- @ >>> 'encode' $ fromList [(\"John\" :: Text, 27), (\"Jane\", 28)]
+-- Chunk \"John,27\\r\\nJane,28\\r\\n\" Empty
+-- @
+--
+-- Since string literals are overloaded we have to supply a type
+-- signature as the compiler couldn't deduce which string type (i.e.
+-- 'String' or 'Text') we want to use. In most cases type inference
+-- will infer the type from the context and you can omit type
+-- signatures.
+--
+-- A short decoding usage example:
+--
+-- @ >>> 'decode' \"John,27\\r\\nJane,28\\r\\n\" :: Either String (Vector (Text, Int))
+-- Right (fromList [(\"John\",27),(\"Jane\",28)])
+-- @
+
+-- $encoding
+--
+-- Encoding and decoding is a two step process. To encode a value, it
+-- is first converted to a generic representation, using either
+-- 'ToRecord' or 'ToNamedRecord'. The generic representation is then
+-- encoded as CSV data. To decode a value the process is reversed and
+-- either 'FromRecord' or 'FromNamedRecord' is used instead. Both
+-- these steps are combined in the 'encode' and 'decode' functions.
+
 -- $typeconversion
 --
 -- There are two ways to convert CSV records to and from and

Data/Ceason/Conversion.hs

@@ -343,6 +343,19 @@ instance ToField a => ToNamedRecord (BSHashMap a) where
 class FromField a where
     parseField :: Field -> Parser a
 
+-- | A type that can be converted to a single CSV field.
+--
+-- Example type and instance:
+--
+-- @{-\# LANGUAGE OverloadedStrings \#-}
+--
+-- data Color = Red | Green | Blue
+--
+-- instance ToField Color where
+--     toField Red   = \"R\"
+--     toField Green = \"G\"
+--     toField Blue  = \"B\"
+-- @
 class ToField a where
     toField :: a -> Field
 
@@ -501,18 +514,22 @@ instance ToField L.ByteString where
     toField = toField . B.concat . L.toChunks
     {-# INLINE toField #-}
 
+-- | Assumes UTF-8 encoding.
 instance FromField T.Text where
     parseField = pure . T.decodeUtf8
     {-# INLINE parseField #-}
 
+-- | Uses UTF-8 encoding.
 instance ToField T.Text where
     toField = toField . T.encodeUtf8
     {-# INLINE toField #-}
 
+-- | Assumes UTF-8 encoding.
 instance FromField LT.Text where
     parseField s = pure (LT.fromChunks [T.decodeUtf8 s])
     {-# INLINE parseField #-}
 
+-- | Uses UTF-8 encoding.
 instance ToField LT.Text where
     toField = toField . B.concat . L.toChunks . LT.encodeUtf8
     {-# INLINE toField #-}
@@ -607,7 +624,10 @@ type Failure f r   = String -> f r
 -- | Success continuation.
 type Success a f r = a -> f r
 
--- | A continuation-based parser type.
+-- | Conversion of a field to a value might fail e.g. if the field is
+-- malformed. This possibility is captured by the 'Parser' type, which
+-- lets you compose several field conversions together in such a way
+-- that if any of them fail, the whole record conversion fails.
 newtype Parser a = Parser {
       runParser :: forall f r.
                    Failure f r