 
 -- | Creates a new caps containing all the formats that are in the
 --   first but not the second.
-capsSubtract :: Caps
-             -> Caps
-             -> Caps
+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 >>=


-- | Append the structure to the current caps, if it is not already
--   expressed by the caps.
capsMergeStructure :: Structure
                   -> CapsM ()
capsMergeStructure structure = do
  capsPtr <- askCapsPtr

--   
--   This function does not work reliably if optional properties for
--   caps are included on one caps and omitted on the other.
capsIsSubset :: Caps -- ^ @caps1@ - the first 'Caps'
             -> Caps -- ^ @caps2@ - the second 'Caps'
             -> Bool -- ^ 'True' if @caps1@ is a subset of @caps2@, otherwise 'False'
capsIsSubset caps1 caps2 =
    toBool $ unsafePerformIO $
        {# call caps_is_subset #} caps1 caps2

-- | Creates a new caps containing all the formats that are common to
--   both of the caps.
capsIntersect :: Caps -- ^ @caps1@ - the first 'Caps'
              -> Caps -- ^ @caps2@ - the second 'Caps'
              -> Caps -- ^ a new 'Caps' containing all capabilities present
                      --   in both @caps1@ and @caps2@
capsIntersect caps1 caps2 =
    unsafePerformIO $
        {# call caps_intersect #} caps1 caps2 >>=
