@@ -40,6 +40,26 @@ import Control.Monad.Trans.Class
4040
4141import Data.Vector ((!))
4242
43+-- | A collection type that can be converted from a sequence of fields.
44+-- Instances are provided for tuples up to 10 elements and lists of any length.
45+--
46+-- Note that instances can defined outside of postgresql-simple, which is
47+-- often useful. For example, here's an instance for a user-defined pair:
48+--
49+-- @data User = User { name :: String, fileQuota :: Int }
50+--
51+-- instance 'FromRow' User where
52+-- fromRow = User \<$\> 'field' \<*\> 'field'
53+-- @
54+--
55+-- The number of calls to 'field' must match the number of fields returned
56+-- in a single row of the query result. Otherwise, a 'ConversionFailed'
57+-- exception will be thrown.
58+--
59+-- Note that 'field' evaluates it's result to WHNF, so the caveats listed in
60+-- previous versions of postgresql-simple no longer apply. Instead, look
61+-- at the caveats associated with user-defined implementations of 'fromRow'.
62+
4363class FromRow a where
4464 fromRow :: RowParser a
4565