 -- | 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 :: Caps -- ^ @caps1@ - the first 'Caps'
+          -> Caps -- ^ @caps2@ - the second 'Caps'
+          -> Caps -- ^ a new 'Caps' containing all capabilities present
+                  --   in either @caps1@ and @caps2@
 capsUnion caps1 caps2 =
     unsafePerformIO $
         {# call caps_union #} caps1 caps2 >>=

           return (caps, result)

-- | Create a caps and mutate it according to the given action.
capsCreate :: CapsM a
           -> (Caps, a)
capsCreate action =
    marshalCapsModify
        {# call caps_new_empty #}
        action

-- | 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

-- | Append the given structure to the current caps.
capsAppendStructure :: Structure
                    -> CapsM ()
capsAppendStructure structure = do
  capsPtr <- askCapsPtr


-- | 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 >>=
