diff --git a/Data/Yoko.hs b/Data/Yoko.hs
--- a/Data/Yoko.hs
+++ b/Data/Yoko.hs
@@ -2,12 +2,51 @@
   MultiParamTypeClasses, FlexibleInstances, ConstraintKinds,
   ScopedTypeVariables, UndecidableInstances #-}
 
+{- |
+
+Module      :  Data.Yoko
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+This omnibus module is the only necessary import for using the @yoko@ generic
+programming library.
+
+However, some sophisticated functions' types might need to import the
+"Data.Yoko.TypeBasics" or "Data.Yoko.Each" modules.
+
+The "Data.Yoko.HCompos" function defines the generic homomorphism; see the
+paper \"A Pattern for Almost Homomorphic Functions\" at
+<http://www.ittc.ku.edu/~nfrisby/papers/yoko.pdf>, submitted to ICFP 2012.
+
+@dc@ type variables abstract over /fields types/.
+
+@dcs@ and @sum@ type variables abstract over sums of /fields types/.
+
+Types of the form @'DCsOf' t dcs@ are /disbanded data types/; for each fields
+type @dc@ in @dcs@, @'Range' dc ~ t@.
+
+A Template Haskell deriver is provided in the "Data.Yoko.TH" module.
+
+-}
+
 module Data.Yoko
-  (Equal,
-   module Data.Yoko.Representation,
-   module Data.Yoko.TypeSums,
+  (module Data.Yoko.Representation,
    module Data.Yoko.View,
-   module Data.Yoko,
+   -- * Building fields type consumers
+   one, (||.), (.||), (.|.),
+   -- * Operations on disbanded data types
+   disbanded, band, ConDCOf, exact_case,
+   -- * Operations on sums of fields types
+   (:-:), Embed, Partition,
+   inject, partition, project,
+   -- * Forgetting @yoko@'s extra structure
+   reps, EachGeneric, EachRep, ig_from,
+   Equal,
+   -- * Bundled Template Haskell
    module Data.Yoko.TH) where
 
 import Data.Yoko.TypeBasics
@@ -23,22 +62,32 @@
 
 
 
-
+-- | @one@ extends a function that consumes a fields type to a function that
+-- consumes a disbanded data type containing just that fields type.
 one :: (dc -> a) -> DCsOf (Range dc) (N dc) -> a
 one = (. unDCsOf) . foldN
 
-infixl 9 .|.   ;   f .|. g = one f ||| one g
-infixr 8 .||   ;   f .|| g = one f ||| g
-infixl 8 ||.   ;   f ||. g = f ||| one g
-
+infixl 9 .|.
+infixr 8 .||, ||.
+-- | @f .|. g = one f '|||' one g@
+f .|. g = one f ||| one g
+-- | @f .|| g = one f '|||' g@
+f .|| g = one f ||| g
+-- | @f ||. g = f '|||' one g@
+f ||. g = f ||| one g
 
 
 
 
 
+-- | @disbanded@ injects a fields type into its disbanded range
 disbanded :: Embed (N dc) (DCs (Range dc)) => dc -> Disbanded (Range dc)
 disbanded = DCsOf . TypeSums.inject
 
+-- | @band@s a disbanded data type back into its normal data type.
+--
+-- Since 'Disbanded' is a type family, the range of @band@ determines the @t@
+-- type variable.
 band :: forall t. Each (ConDCOf t) (DCs t) => Disbanded t -> t
 band = each (Proxy :: Proxy (ConDCOf t)) rejoin
 
@@ -46,14 +95,17 @@
 instance (Range dc ~ t, DC dc) => ConDCOf t dc
 
 
-
+-- | @inject@s a fields type into a sum of fields types.
 inject :: Embed (N dc) sum => dc -> sum
 inject = TypeSums.inject
 
+-- | @partition@s a sum of fields type into a specified sum of fields types and
+-- the remaining sum.
 partition :: Partition sum sub (sum :-: sub) =>
              DCsOf t sum -> Either (DCsOf t sub) (DCsOf t (sum :-: sub))
 partition = (DCsOf +++ DCsOf) . TypeSums.partition . unDCsOf
 
+-- | @project@s a single fields type out of a disbanded data type.
 project :: Partition sum (N dc) (sum :-: N dc) =>
            DCsOf (Range dc) sum -> Either dc (DCsOf (Range dc) (sum :-: N dc))
 project = right DCsOf . TypeSums.project . unDCsOf
@@ -61,6 +113,8 @@
 
 
 -- TODO need a MapSum just like MapRs, use a RPV for rep
+
+-- | @reps@ maps a disbanded data type to its sum-of-products representation.
 reps :: EachGeneric sum => DCsOf t sum -> EachRep sum
 reps = repEach . unDCsOf
 
@@ -78,10 +132,25 @@
 
 
 
-
+-- | @exact_case@ is an exactly-typed case: the second argument is the
+-- discriminant, the first argument is the default case, and the third argument
+-- approximates a list of alternatives.
+--
+-- @
+-- exact_case default x $
+--   (\(C0_ ...) -> ...) '.||'
+--   (\(C1_ ...) -> ...) '.|.'
+--   (\(C2_ ...) -> ...)
+-- @
+--
+-- In this example, @C0_@, @C1_@, and @C2_@ are fields types. The other fields
+-- types for the same data type are handled with the @default@ function.
 exact_case :: (DT t, Partition (DCs t) dcs (DCs t :-: dcs)) =>
   (DCsOf t (DCs t :-: dcs) -> a) -> t -> (DCsOf t dcs -> a) -> a
 exact_case g x f =
   either f g $ partition $ disband x
 
+-- | @ig_from x =@ 'reps $ disband' @x@ is a convenience. It approximates the
+-- @instant-generics@ view, less the @CEq@ annotations.
+ig_from :: (DT t, EachGeneric (DCs t)) => t -> EachRep (DCs t)
 ig_from x = reps $ disband x
diff --git a/Data/Yoko/Each.hs b/Data/Yoko/Each.hs
--- a/Data/Yoko/Each.hs
+++ b/Data/Yoko/Each.hs
@@ -1,14 +1,31 @@
 {-# LANGUAGE KindSignatures, ConstraintKinds, MultiParamTypeClasses,
   Rank2Types, FlexibleInstances, UndecidableInstances, TypeOperators #-}
 
+{- |
+
+Module      :  Data.Yoko.Each
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+Basic support for folding through type-level sums.
+
+-}
+
 module Data.Yoko.Each (Each, each) where
 
 import Data.Yoko.TypeBasics
 import Data.Yoko.Representation
 
 
-
+-- | The constraint @Each con sum@ corresponds to the constraing @forall dc in
+-- sum. con dc@.
 type Each = Each_
+
+-- | Fold through a type-level sum.
 each :: Each cxt sum => Proxy cxt -> (forall a. cxt a => a -> b) -> sum -> b
 each = each_
 
diff --git a/Data/Yoko/HCompos.hs b/Data/Yoko/HCompos.hs
--- a/Data/Yoko/HCompos.hs
+++ b/Data/Yoko/HCompos.hs
@@ -4,13 +4,27 @@
 
 {-# OPTIONS_GHC -fcontext-stack=250 #-}
 
-module Data.Yoko.HCompos (Idiom, HCompos(..)) where
+{- |
 
-import Data.Yoko.TypeBasics
-import Data.Yoko
+Module      :  Data.Yoko.HCompos
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
 
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
 
+The generic homomorphism or \"heterogenous compos\".
 
+See the paper \"A Pattern for Almost Homomorphic Functions\" at <http://www.ittc.ku.edu/~nfrisby/papers/yoko.pdf>, submitted to ICFP 2012.
+
+-}
+
+module Data.Yoko.HCompos (Idiom, HCompos(..), FindDCs) where
+
+import Data.Yoko.TypeBasics
+import Data.Yoko
+
 import Control.Applicative
 
 
@@ -23,8 +37,9 @@
 
 
 
-
+-- | The applicative functor required by the conversion.
 type family Idiom cnv :: * -> *
+-- | The conversion @cnv@ can convert from @a@ to @t@.
 class Applicative (Idiom cnv) => HCompos cnv a t where
   hcompos :: cnv -> a -> Idiom cnv t
 
@@ -46,6 +61,8 @@
 
 
 
+-- | @FindDCs s sum@ returns a type-level @Maybe@. @Just dc@ is a fields type
+-- @dc@ where @'Tag' dc ~ s@.
 type family FindDCs s sum
 type instance FindDCs s (N dc) =
   If (Equal s (Tag dc)) (Just (N dc)) Nothing
diff --git a/Data/Yoko/MaybeKind.hs b/Data/Yoko/MaybeKind.hs
--- a/Data/Yoko/MaybeKind.hs
+++ b/Data/Yoko/MaybeKind.hs
@@ -1,20 +1,27 @@
 {-# LANGUAGE TypeFamilies, EmptyDataDecls #-}
 
-module Data.Yoko.MaybeKind where
+module Data.Yoko.MaybeKind
+  (-- ** Type-level @Maybe@
+   Nothing, Just,
+   IsJust, MaybePlus1, MaybeMap
+   ) where
 
 import Type.Booleans
 
 data Nothing
 data Just (x :: *)
 
+-- | Returns a type-level boolean from @type-booleans@.
 type family IsJust (x :: *) :: * -- returns Bool, ideally
 type instance IsJust Nothing = False
 type instance IsJust (Just x) = True
 
+-- | Type-level @mplus@ for @Maybe@.
 type family MaybePlus1 (x :: *) (y :: *) :: *
 type instance MaybePlus1 Nothing y = y
 type instance MaybePlus1 (Just x) Nothing = Just x
 
+-- | Type-level @fmap@ for @Maybe@.
 type family MaybeMap (f :: * -> *) (x :: *) :: *
 type instance MaybeMap f (Just x) = Just (f x)
 type instance MaybeMap f Nothing = Nothing
diff --git a/Data/Yoko/Representation.hs b/Data/Yoko/Representation.hs
--- a/Data/Yoko/Representation.hs
+++ b/Data/Yoko/Representation.hs
@@ -1,40 +1,92 @@
 {-# LANGUAGE TypeFamilies, TypeOperators, TemplateHaskell,
   UndecidableInstances, EmptyDataDecls #-}
 
-module Data.Yoko.Representation where
+{- |
 
+Module      :  Data.Yoko.Representation
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+The @yoko@ representation types.
+
+-}
+
+module Data.Yoko.Representation
+  (-- * Representation
+   -- ** Sums
+   Void(..), N(..), (:+:)(..), DCsOf(..),
+   -- ** Products
+   U(..), (:*:)(..),
+   -- ** Fields
+   Rec(..), Dep(..), Par1(..), Par2(..),
+   -- ** Conversions to and from fields-of-products structure
+   Rep, Generic(..),
+   -- ** Building disbanded data type consumers
+   (|||),
+   -- ** Auxilliaries
+   unDCsOf, unN, foldN, mapN,
+   foldPlus, mapPlus,
+   foldTimes, mapTimes,
+   unRec, mapRec, unDep, unPar1, unPar2,
+   DistMaybePlus
+   ) where
+
 import Data.Yoko.TypeBasics
 
 
 
+-- | The empty product.
 data U = U
+
 infixr 6 :*:
+-- | Product union.
 data a :*: b = a :*: b
 
+-- | The empty sum. Used as an error type instead of a represention type, since
+-- data types with no constructors are uninteresting from a generic programming
+-- perspective -- there's just not much to be done generically.
 data Void
+
+-- | The singleton sum.
 newtype N a = N a
+
 infixl 6 :+:
+-- | Sum union.
 data a :+: b = L a | R b deriving (Eq, Show, Ord, Read)
 
 
-
+-- | Representation of unary type application. @f@ is a genuine @*->*@ type,
+-- not a representation. @a@ is a representation.
 newtype Par1 f a = Par1 (f a)
-newtype Par2 f a b = Par2 (f a b)
 
+-- | Representation of binary type application. @f@ is a genuine @*->*->*@
+-- type, not a representation. @a@ and @b@ are representations.
+newtype Par2 f a b = Par2 (f a b)
 
 
+-- | A non-recursive occurrence.
 newtype Dep a = Dep a
+
+-- | A recursive occurrence.
 newtype Rec a = Rec a
 
 
 
+-- | A mapping to the structural representation of a fields type: just products
+-- of fields, no sums -- fields types have just one constructor.
 type family Rep a
 
 
 
+-- | Converts between a fields type and its product-of-fields structure.
 class Generic a where rep :: a -> Rep a; obj :: Rep a -> a
 
 
+
 unDep (Dep x) = x
 
 unRec (Rec x) = x
@@ -59,6 +111,9 @@
 
 
 
+-- | We avoid empty sums with a type-level @Maybe@. @DistMaybePlus@ performs
+-- sum union on lifted sums, only introducing @:+:@ when both arguments are
+-- @Just@s.
 type family DistMaybePlus a b
 type instance DistMaybePlus Nothing b = b
 type instance DistMaybePlus (Just a) Nothing = Just a
@@ -81,11 +136,15 @@
 
 
 
--- carrying around the original type supplants many ascriptions
+-- | A disbanded data type is an application of @DCsOf t@ to a sum of fields
+-- types all of which have @t@ as their range. The use of @DCsOf@'s first
+-- parameter throughout the API (e.g. in '|||') supplants many ascriptions.
 newtype DCsOf t sum = DCsOf sum   ;   unDCsOf (DCsOf x) = x
 instance Functor (DCsOf t) where fmap f = DCsOf . f . unDCsOf
 
 infixl 6 |||
+-- | Combines two functions that consume disbanded data types into a function
+-- that consumes their union. All fields types must be from the same data type.
 (|||) :: (DCsOf t sumL -> a) -> (DCsOf t sumR -> a) ->
          DCsOf t (sumL :+: sumR) -> a
 (|||) f g = foldPlus f g . mapPlus DCsOf DCsOf . unDCsOf
diff --git a/Data/Yoko/TH.hs b/Data/Yoko/TH.hs
--- a/Data/Yoko/TH.hs
+++ b/Data/Yoko/TH.hs
@@ -1,7 +1,48 @@
 {-# LANGUAGE TypeOperators, ViewPatterns, TemplateHaskell, PatternGuards #-}
 
+{- |
+
+Module      :  Data.Yoko.TH
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+This bundled Template Haskell derives all fields types and @yoko@ instances for
+users' data types.
+
+'yokoTH' is the prinicpal deriver, but it can be customized via 'yokoTH_with',
+which lets the user specify how to represent composite fields that include
+applications of type with higher-kinds than @*->*@.
+
+For instance, @yokoTH@ cannot handle @data T = C0 | C1 [(Int, T T)]@.
+
+The following invocation of @yokoTH_with@ does. @Par2@ is declared in
+"Data.Yoko.Representation", but @Bifunctor@ is not.
+
+@
+class Bifunctor f where
+  bifmap :: (a -> c) -> (b -> d) -> f a b -> f c d
+
+instance Bifunctor ((,,) a) where
+  bifmap f g ~(a, x, y) = (a, f x, g y)
+
+yokoTH_with (yokoDefaults {mappings = ((2, Mapping ''Par2 'Par2 'bifmap) :)}) ''T
+@
+
+As always, use @{- OPTIONS_GHC -ddump-splices -}@ to inspect the generated
+code.
+
+-}
+
 module Data.Yoko.TH
-  (yokoTH, yokoTH_with, yokoDefaults, YokoOptions(..), Mapping(..)) where
+  (-- * Derivers
+   yokoTH, yokoTH_with,
+   -- * Options
+   YokoOptions(..), Mapping(..), yokoDefaults
+  ) where
 
 import Type.Spine.Stage0 (Spine, spineType_, kTypeG)
 import Type.Serialize (serializeTypeAsHash_)
@@ -56,14 +97,23 @@
 
 
 
+-- | A 'Mapping' identifies the representation type, its constructor, and the
+-- associated mapping function. For example, 'Par1' is represented with
+-- @Mapping ''Par1 'Par1 'fmap@.
 data Mapping = Mapping
   {containerTypeName :: Name, containerCtor :: Name,
    methodName :: Name}
 
+-- | The default @yoko@ derivations can be customised.
 data YokoOptions = YokoOptions
-  {renamer :: (String -> String) -> (String -> String),
+  { -- | How fields type names are derived from constructor names. Defaults to
+    -- @(++ \"_\")@.
+   renamer :: (String -> String) -> (String -> String),
+    -- | How applications of higher-rank data types are represented. Defaults
+    -- to @[(1, 'Mapping' ''Par1 'Par1 'fmap)]@.
    mappings :: [(Int, Mapping)] -> [(Int, Mapping)]}
 
+-- | The default options. @yokoDefaults = YokoOptions id id@.
 yokoDefaults :: YokoOptions
 yokoDefaults = YokoOptions id id
 
@@ -80,9 +130,11 @@
 
 
 
+-- | Derive fields types and all @yoko@ instances for a given data type.
 yokoTH :: Name -> Q [Dec]
 yokoTH n = yokoTH_with yokoDefaults n
 
+-- | Customized derivation.
 yokoTH_with :: YokoOptions -> Name -> Q [Dec]
 yokoTH_with options n = runM $ yoko0 $ X :&
   Target := n :& Renamer := (mkName . renamer options (++ "_") . TH.nameBase)
diff --git a/Data/Yoko/TypeBasics.hs b/Data/Yoko/TypeBasics.hs
--- a/Data/Yoko/TypeBasics.hs
+++ b/Data/Yoko/TypeBasics.hs
@@ -1,18 +1,28 @@
 {-# LANGUAGE TypeFamilies, UndecidableInstances, DataKinds, PolyKinds #-}
 
+{- |
+
+Module      :  Data.Yoko.TypeBasics
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+Some type-level programming basics.
+
+-}
+
 module Data.Yoko.TypeBasics (
-  module Data.Yoko.MaybeKind,
-  module Type.Booleans,
-  Proxy(..),
-  Equal,
-  IsPrefixOf,
-  derive, encode
+  Proxy(..), Equal, derive,
+  -- ** Re-exports
+  module Data.Yoko.MaybeKind, module Type.Booleans, encode
   ) where
 
 import Type.Booleans
 import Data.Yoko.MaybeKind
 
---import Data.Proxy.TH (Proxy(..))
 import Type.Spine
 import Type.Ord (IsEQ)
 import Type.Serialize
@@ -20,18 +30,19 @@
 
 
 
+-- | A polykinded proxy.
 data Proxy a = Proxy
 
 
 
+-- | Convenient synonym. @type Equal a b = 'IsEQ' ('Compare' a b)@
 type Equal a b = IsEQ (Compare a b)
 
 
 
-type family IsPrefixOf (pre :: *) (s :: *) :: * -- emulated primitive
-
-
-
+-- | Template Haskell derivation for the @type-spine@ and @type-cereal@
+-- packages' 'Spine' and 'Serialize' type families, which support generic
+-- instances of 'Compare'.
 derive n = do
   d <- spineType n
   (d ++) `fmap` serializeTypeAsHash n
diff --git a/Data/Yoko/View.hs b/Data/Yoko/View.hs
--- a/Data/Yoko/View.hs
+++ b/Data/Yoko/View.hs
@@ -2,8 +2,28 @@
   MultiParamTypeClasses, FlexibleInstances, ConstraintKinds,
   UndecidableInstances #-}
 
-module Data.Yoko.View where
+{- |
 
+Module      :  Data.Yoko.View
+Copyright   :  (c) The University of Kansas 2011
+License     :  BSD3
+
+Maintainer  :  nicolas.frisby@gmail.com
+Stability   :  experimental
+Portability :  see LANGUAGE pragmas (... GHC)
+
+The @yoko@ generic view.
+
+-}
+
+module Data.Yoko.View
+  (-- * Reflection
+   -- ** Fields types
+   Tag, Range, DC(..),
+   -- ** Disbanded data types
+   DCs, Disbanded, DT(..)
+  ) where
+
 import Data.Yoko.Representation
 import Data.Yoko.TypeSums (Embed, Partition, (:-:))
 import Data.Yoko.Each
@@ -11,14 +31,23 @@
 
 
 
-
+-- | @Tag@ returns a simulated type-level string that is the name of the
+-- constructor that the @dc@ fields type represents.
 type family Tag dc
 
+-- | @Range@ is the data type that contains the constructor that the fields
+-- type @dc@ represents.
 type family Range dc
+
+-- | Any fields type can be further represented as a product-of-fields and can
+-- be injected back into the original data type.
 class (Generic dc, DT (Range dc)) => DC dc where rejoin :: dc -> Range dc
 
+-- | The @DCs@ of a data type is sum of all of its fields types.
 type family DCs t
+-- | A disbanded data type is the data type's @DCs@ annotated with it.
 type Disbanded t = DCsOf t (DCs t)
+-- | @DT@ disbands a data type if all of its fields types have @DC@ instances.
 class Each IsDCOf (DCs t) => DT t where disband :: t -> Disbanded t
 
 class (Partition (DCs (Range dc)) (N dc) (DCs (Range dc) :-: N dc),
diff --git a/yoko.cabal b/yoko.cabal
--- a/yoko.cabal
+++ b/yoko.cabal
@@ -1,5 +1,5 @@
 name: yoko
-version: 0.3.1.2
+version: 0.3.1.3
 synopsis: Generic Programming with Disbanded Data Types
 
 description: