            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

        _ = {# call structure_copy #}

-- | Removes the structure at the given index from the current caps.
capsRemoveStructure :: Word
                    -> CapsM ()
capsRemoveStructure idx = do
  capsPtr <- askCapsPtr


-- | Creates a new caps that represents the same set of formats as the
--   argument, but that contains no lists.
capsNormalize :: Caps -- ^ @caps@ - a 'Caps'
              -> Caps -- ^ the new, normalized 'Caps'
capsNormalize caps =
    unsafePerformIO $
        {# call caps_normalize #} caps >>= takeCaps

-- | Converts the argument to a string representation. The string can
--   be converted back to a caps using 'capsFromString'.
capsToString :: Caps   -- ^ @caps@ - a 'Caps'
             -> String -- ^ the string representation of 'Caps'
capsToString caps =
    unsafePerformIO $
        {# call caps_to_string #} caps >>= readUTFString

-- | Read a caps from a string.
capsFromString :: String     -- ^ @string@ - the string representation of a 'Caps'
               -> Maybe Caps -- ^ the new 'Caps', or 'Nothing' if @string@ is invalid
capsFromString string =
    unsafePerformIO $
        withUTFString string {# call caps_from_string #} >>=
