 
 -- | Returns 'True' if the caps are equal.  The caps must both be
 --   fixed.
-capsIsEqualFixed :: Caps
-                 -> Caps
-                 -> Bool
+capsIsEqualFixed :: Caps -- ^ @caps1@ - the first 'Caps'
+                 -> Caps -- ^ @caps2@ - the second 'Caps'
+                 -> Bool -- ^ 'True' if both 'Caps' represent the same set
+                         --   of capabilities
 capsIsEqualFixed caps1 caps2 =
     toBool $ unsafePerformIO $
         {# call caps_is_equal_fixed #} caps1 caps2


-- | Creates a new caps that represents the same set of formats as the
--   argument, but that contains no lists.
capsNormalize :: Caps
              -> 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
             -> String
capsToString caps =
    unsafePerformIO $
        {# call caps_to_string #} caps >>= readUTFString

-- | Read a caps from a string.
capsFromString :: String
               -> Maybe Caps
capsFromString string =
    unsafePerformIO $
        withUTFString string {# call caps_from_string #} >>=

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