            return (caps, result)
 
 -- | Create a caps and mutate it according to the given action.
-capsCreate :: CapsM a
-           -> (Caps, a)
-capsCreate action =
+capsCreate :: CapsM a   -- ^ @mutate@ - the mutating action
+           -> (Caps, a) -- ^ the new 'Caps' and the action's result
+capsCreate mutate =
     marshalCapsModify
         {# call caps_new_empty #}
-        action
+        mutate
 
 -- | Copy a caps and mutate it according to the given action.
-capsModify :: Caps
-           -> CapsM a
-           -> (Caps, a)
-capsModify caps action =
-    marshalCapsModify ({# call caps_copy #} caps) action
+capsModify :: Caps      -- ^ @caps@ - the 'Caps' to modify
+           -> CapsM a   -- ^ @mutate@ - the mutating action
+           -> (Caps, a) -- ^ the new 'Caps' and the action's result
+capsModify caps mutate =
+    marshalCapsModify ({# call caps_copy #} caps) mutate
 
 -- | Append the given structure to the current caps.
-capsAppendStructure :: Structure
+capsAppendStructure :: Structure -- ^ @structure@ - the 'Structure' to append to the current 'Caps'
                     -> CapsM ()
 capsAppendStructure structure = do
   capsPtr <- askCapsPtr

-- | Creates a new caps containing all the formats that are common to
--   either of the caps. If either of the structures are equivalient
--   to 'capsAny', the result will be 'capsAny'.
capsUnion :: Caps
          -> Caps
          -> Caps
capsUnion caps1 caps2 =
    unsafePerformIO $
        {# call caps_union #} caps1 caps2 >>=


-- | Creates a new caps containing all the formats that are in the
--   first but not the second.
capsSubtract :: Caps -- ^ @caps1@ - the first 'Caps'
             -> Caps -- ^ @caps2@ - the second 'Caps'
             -> Caps -- ^ a new 'Caps' containing all capabilities present
                     --   in @caps1@ but not @caps2@
capsSubtract caps1 caps2 =
    unsafePerformIO $
        {# call caps_subtract #} caps1 caps2 >>=
