 --   
 --   This function does not work reliably if optional properties for
 --   caps are included on one caps and omitted on the other.
-capsIsSubset :: Caps
-             -> Caps
-             -> Bool
+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
-              -> Caps
-              -> 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 >>=


-- | Returns 'True' if the caps are equal.  The caps must both be
--   fixed.
capsIsEqualFixed :: Caps
                 -> Caps
                 -> Bool
capsIsEqualFixed caps1 caps2 =
    toBool $ unsafePerformIO $
        {# call caps_is_equal_fixed #} caps1 caps2

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