 capsAny =
     unsafePerformIO $ {# call caps_new_any #} >>= takeCaps
 
--- | Returns the number of structures contained in the 'Caps'.
-capsSize :: Caps
-         -> Word
+-- | Get the number of structures contained in the 'Caps'.
+capsSize :: Caps -- ^ @caps@ - a 'Caps'
+         -> Word -- ^ the number of structures contained in the 'Caps'
 capsSize caps =
     fromIntegral $ unsafePerformIO $ {# call caps_get_size #} caps
 
--- | Returns the 'Structure' at the given index.
-capsGetStructure :: Caps
-                 -> Word
-                 -> Maybe Structure
+-- | Get the 'Structure' at the given index.
+capsGetStructure :: Caps            -- ^ @caps@ - a 'Caps'
+                 -> Word            -- ^ @index@ - the index of the 'Structure'
+                 -> Maybe Structure -- ^ the 'Structure' at the given index, or 'Nothing'
+                                    --   if @index@ is invalid
 capsGetStructure caps index =
     unsafePerformIO $
         {# call caps_get_structure #} caps (fromIntegral index) >>=
             maybePeek peekStructure
 
--- | Returns a new 'Caps' containing only the 'Structure' at the given
+-- | Create a new 'Caps' containing only the 'Structure' at the given
 --   index of the caps.
-capsCopyNth :: Caps
-            -> Word
-            -> Maybe Caps
+capsCopyNth :: Caps       -- ^ @caps@ - a 'Caps'
+            -> Word       -- ^ @index@ - the index of the 'Structure'
+            -> Maybe Caps -- ^ the new 'Caps', or 'Nothing'
+                          --   if @index@ is invalid
 capsCopyNth caps index =
     unsafePerformIO $
         {# call caps_copy_nth #} caps (fromIntegral index) >>=
             maybePeek takeCaps
 
--- | Returns 'True' if the caps represents no media formats.
-capsIsEmpty :: Caps
-            -> Bool
+-- | Determine whether @caps@ represents no media formats.
+capsIsEmpty :: Caps -- ^ @caps@ - a 'Caps'
+            -> Bool -- ^ 'True' if @caps@ is empty, otherwise 'False'
 capsIsEmpty caps =
     toBool $ unsafePerformIO $
         {# call caps_is_empty #} caps
 
--- | Returns 'True' if the caps is fixed.
-capsIsFixed :: Caps
-            -> Bool
+-- | Determine whether the @caps@ is fixed; that is, if it has exactly
+--   one structure, and each field in the structure describes a fixed type.
+capsIsFixed :: Caps -- ^ @caps@ - a 'Caps'
+            -> Bool -- ^ 'True' if @caps@ is fixed, otherwise 'False'
 capsIsFixed caps =
     toBool $ unsafePerformIO $
         {# call caps_is_fixed #} caps
 
 -- | Returns 'True' if the caps represent the same set of capabilities.
-capsIsEqual :: Caps
-            -> Caps
-            -> Bool
+--   
+--   This function does not work reliably if optional properties for
+--   'Caps' are included on one 'Caps' but omitted on the other.
+capsIsEqual :: Caps -- ^ @caps1@ - the first 'Caps'
+            -> Caps -- ^ @caps2@ - the second 'Caps'
+            -> Bool -- ^ 'True' if both 'Caps' represent the same set
+                    --   of capabilities.
 capsIsEqual caps1 caps2 =
     toBool $ unsafePerformIO $
         {# call caps_is_equal #} 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 >>=
