Documentation

CoreFoundation/System/CoreFoundation/Array/Mutable.chs

@@ -19,6 +19,7 @@ import System.CoreFoundation.Foreign
 
 #include <CoreFoundation/CoreFoundation.h>
 
+-- | Mutable arrays
 type MArray s a = Mutable s (Array a)
 
 type MArrayRef = Ptr (MutableRepr CFArray)
@@ -40,9 +41,19 @@ getCount arr = unsafePrimToPrim $ c_getCount arr
 {#fun unsafe CFArrayGetCount as c_getCount
     { withMutableObject* `Mutable s (Array a)' } -> `Int' #}
 
+{- | 
+Construct an empty array with the given capacity.
+    
+  [capacity] The maximum number of values that can be contained by the new array. The array starts empty and can grow to this number of values (and it can have less). Pass 0 to specify that the maximum capacity is not limited. The value must not be negative.
+-}
 newMutableArray :: (PrimMonad m, Object a) => Int -> m (MArray (PrimState m) a)
 newMutableArray n = unsafePrimToPrim . getOwned $ cfNewMutableArray n
 
+{- |
+Adds a value to an array giving it the new largest index. If the array is a limited-capacity array and it is full before this operation, the behavior is undefined.
+
+  [Discussion] The value parameter is assigned to the index one larger than the previous largest index and the count of the Array is increased by one.
+-}
 appendValue :: (PrimMonad m, Object a) => MArray (PrimState m) a -> a -> m ()
 appendValue arr v  = unsafePrimToPrim $ c_appendValue arr v
 

CoreFoundation/System/CoreFoundation/Bundle.chs

@@ -26,19 +26,31 @@ import Control.DeepSeq
 declareCFType "Bundle"
 {#pointer CFBundleRef as BundleRef nocode#}
 
+{- |
+Returns an application’s main bundle.
+-}
 {#fun CFBundleGetMainBundle as getMainBundle
     { } -> `Bundle' getAndRetain* #}
 
 {#fun CFBundleCopyExecutableURL as cfGetExecutableURL
     { withObject* `Bundle' } -> `URLRef' id #}
 
+{- |
+Returns the location of a bundle’s main executable code.
+-}
 getExecutableURL :: Bundle -> IO URL
 getExecutableURL bundle = getOwned $ cfGetExecutableURL bundle
 
 {#fun CFBundleCopyAuxiliaryExecutableURL as cfGetAuxiliaryExecutableURL
     { withObject* `Bundle' 
     , withObject* `String' } -> `URLRef' id #}
 
+{- |
+Returns the location of a bundle’s auxiliary executable code.
+
+  [Discussion] This function can be used to find executables other than your main executable. This is useful, for instance, for applications that have some command line tool that is packaged with and used by the application. The tool can be packaged in the various platform executable directories in the bundle and can be located with this function. This allows an application to ship versions of the tool for each platform as it does for the main application executable.
+
+-}
 getAuxiliaryExecutableURL :: Bundle -> String -> IO URL
 getAuxiliaryExecutableURL bundle str = getOwned $ cfGetAuxiliaryExecutableURL bundle str
 
@@ -49,7 +61,27 @@ getAuxiliaryExecutableURL bundle str = getOwned $ cfGetAuxiliaryExecutableURL bu
     , withMaybeObject* `Maybe String'
     } -> `URLRef' id #}
 
-getResourceURL :: Bundle -> String -> Maybe String -> Maybe String -> IO URL
+{- |
+Returns the location of a resource contained in the specified bundle.
+
+For example, if a bundle contains a subdirectory WaterSounds that includes a file Water1.aiff, you can retrieve the URL for the file using
+
+> getResourceURL bundle "Water1" (Just "aiff") (Just "WaterSounds")
+
+-}
+getResourceURL :: 
+     Bundle
+     -- ^ The bundle to examine.
+
+  -> String 
+     -- ^ The name of the requested resource
+  -> Maybe String 
+     -- ^ The abstract type of the requested resource. The type is expressed as a filename extension, such as jpg. Pass @Nothing@ if you don't need to search by type.
+
+  -> Maybe String
+     -- ^ The name of the subdirectory of the bundle's resources directory to search. Pass @Nothing@ to search the standard Bundle resource locations.
+
+  -> IO URL
 getResourceURL a b c d = getOwned $ cfGetResourceURL a b c d
 
 deriving instance Typeable Bundle

CoreFoundation/System/CoreFoundation/Error.chs

@@ -2,9 +2,11 @@
 -- It is toll-free bridged with the @NSData@ type.
 module System.CoreFoundation.Error (
             -- * The Error type
+            -- $error
             Error,
             ErrorRef,
-            cfError,
+            mkError,
+            ErrorCode,
             -- * Error properties
             errorDescription,
             errorFailureReason,
@@ -13,6 +15,7 @@ module System.CoreFoundation.Error (
             errorDomain,
             errorCode,
             -- * Error domains
+            ErrorDomain,
             domainPOSIX,
             domainOSStatus,
             domainMach,
@@ -38,12 +41,19 @@ import System.CoreFoundation.Foreign
 import System.CoreFoundation.Internal.TH
 import Data.Typeable
 import Control.DeepSeq
+import Control.Exception
 
 #include <CoreFoundation/CoreFoundation.h>
 
 declareCFType "Error"
 {#pointer CFErrorRef as ErrorRef nocode#}
 
+{- $error
+An 'Error' object encapsulates rich and extensible error information than is possible using only an error code or error string. The core attributes of an 'Error' object are an error domain (represented by a string), a domain-specific error code and a user info dictionary containing application specific information. Errors are required to have a domain and an error code within that domain. The optional 'userInfo' dictionary may provide additional information that might be useful for the interpretation and reporting of the error. This dictionary can even contain an \"underlying\" error, which is wrapped as an error bubbles up through various layers. See <https://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFErrorRef/Reference/reference.html#//apple_ref/doc/uid/TP40004341-CH1-DontLinkElementID_13> for further details.
+
+The 'Error' type is an instance of 'Exception', so it may be thrown using 'throw'.
+-}
+
 importCFStringAs "kCFErrorLocalizedDescriptionKey" "localizedDescriptionKey"
 importCFStringAs "kCFErrorLocalizedFailureReasonKey" "localizedFailureReasonKey"
 importCFStringAs "kCFErrorLocalizedRecoverySuggestionKey" "localizedRecoverySuggestionKey"
@@ -55,41 +65,68 @@ importCFStringAs "kCFErrorDomainOSStatus" "domainOSStatus"
 importCFStringAs "kCFErrorDomainMach" "domainMach"
 importCFStringAs "kCFErrorDomainCocoa" "domainCocoa"
 
+-- | Error domains
+type ErrorDomain = String
+domainPOSIX, domainOSStatus, domainMach, domainCocoa :: ErrorDomain
+
+-- | Error codes
+type ErrorCode = CFIndex
+
 {#fun CFErrorCreate as newError
     { withDefaultAllocator- `AllocatorPtr'
     ,  withObject* `String'
-    , `Int'
-    , maybeWithObject* `Maybe (Dictionary k v)'
+    , id `ErrorCode'
+    , maybeWithObject* `Maybe (Dictionary DynObj DynObj)'
     } -> `ErrorRef' id #}
 
-cfError :: String -- ^ The error domain.
-        -> Int -- ^ The error code.
-        -> Maybe (Dictionary k v) -- ^ User info.
+-- | Construct a new error
+mkError :: ErrorDomain -- ^ The error domain.
+        -> ErrorCode -- ^ The error code.
+        -> Maybe (Dictionary DynObj DynObj) -- ^ User info.
         -> Error
-cfError domain code userInfo = unsafePerformIO $ getOwned
+mkError domain code userInfo = unsafePerformIO $ getOwned
             $ newError domain code userInfo
 
 maybeWithObject Nothing = ($ nullPtr)
 maybeWithObject (Just o) = withObject o
 
+{- |
+Returns a human-presentable description for a given error. This is a complete sentence or two which says what failed and why it failed. The structure of the description depends on the details provided in the user info dictionary. See <https://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFErrorRef/Reference/reference.html#//apple_ref/c/func/CFErrorCopyDescription> for the precise rules used.
+-}
 {#fun pure CFErrorCopyDescription as errorDescription
     { withObject* `Error' } -> `String' getAndRetain* #}
 -- The docs say that the CFErrorCopyDescription will never return NULL.
 
+{- |
+Returns a human-presentable failure reason for a given error. See <https://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFErrorRef/Reference/reference.html#//apple_ref/c/func/CFErrorCopyFailureReason> for details.
+
+-}
 {#fun pure CFErrorCopyFailureReason as errorFailureReason
     { withObject* `Error' } -> `Maybe String' maybeGetAndRetain* #}
 
+{- |
+Returns a human presentable recovery suggestion for a given error. See <https://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFErrorRef/Reference/reference.html#//apple_ref/c/func/CFErrorCopyRecoverySuggestion> for details.
+-}
 {#fun pure CFErrorCopyRecoverySuggestion as errorRecoverySuggestion
     { withObject* `Error' } -> `Maybe String' maybeGetAndRetain* #}
 
+{- |
+Returns the user info dictionary.
+-}
 {#fun pure CFErrorCopyUserInfo as userInfo
-    { withObject* `Error' } -> `Maybe (Dictionary k v)' maybeGetAndRetain* #}
+    { withObject* `Error' } -> `Maybe (Dictionary DynObj DynObj)' maybeGetAndRetain* #}
 
+{- |
+Returns the error domain.
+-}
 {#fun pure CFErrorGetDomain as errorDomain
-    { withObject* `Error' } -> `String' getAndRetain* #}
+    { withObject* `Error' } -> `ErrorDomain' getAndRetain* #}
 
+{- |
+Returns the error code.
+-}
 {#fun pure CFErrorGetCode as errorCode
-    { withObject* `Error' } -> `CFIndex' id #} 
+    { withObject* `Error' } -> `ErrorCode' id #} 
 
 toPair :: Error -> (String, CFIndex)
 toPair err = (errorDomain err, errorCode err)
@@ -102,3 +139,4 @@ instance Ord Error where
   compare a b = compare (toPair a) (toPair b)
 instance Show Error where
   show = getChars . errorDescription
+instance Exception Error

CoreFoundation/System/CoreFoundation/NotificationCenter.chs

@@ -1,11 +1,16 @@
--- | Notification centers.  This is *not* toll-free bridged with @NSNotificationCenter@.
+{- | Notification centers.  This is *not* toll-free bridged with @NSNotificationCenter@.
+
+A 'NotificationCentre' object provides the means by which you can send a message, or notification, to any number of recipients, or observers, without having to know anything about the recipients. A notification message consists of a notification name (a 'String'), a pointer value that identifies the object posting the notification, and an optional dictionary that contains additional information about the particular notification. See <https://developer.apple.com/library/mac/#documentation/CoreFoundation/Reference/CFNotificationCenterRef/Reference/reference.html> for further details.
+-}
+
 module System.CoreFoundation.NotificationCenter (
                             NotificationCenter,
                             NotificationCenterRef,
                             getLocalCenter,
                             postNotification,
                                 ) where
 
+import Foreign.Marshal
 import Foreign.Ptr
 import Foreign.C
 import Prelude hiding (String)
@@ -24,15 +29,45 @@ import System.CoreFoundation.Internal.TH
 declareCFType "NotificationCenter"
 {#pointer CFNotificationCenterRef as NotificationCenterRef nocode#}
 
+{- | 
+Returns the application's local notification center. An application has only one local notification center, so this function returns the same value each time it is called.
+-}
 {#fun CFNotificationCenterGetLocalCenter as getLocalCenter
     { } -> `NotificationCenter' getAndRetain* #}
 
-{#fun CFNotificationCenterPostNotification as postNotification
+-- | Posts a notification for an object. For more details, see <https://developer.apple.com/library/mac/documentation/CoreFoundation/Reference/CFNotificationCenterRef/Reference/reference.html#//apple_ref/c/func/CFNotificationCenterPostNotification>
+postNotification ::
+    NotificationCenter 
+    -- ^ The notification center to post the notification.
+
+ -> String 
+    -- ^ The name of the notification to post.
+
+ -> Ptr () 
+    -- ^ The object posting the notification.
+
+ -> Maybe (Dictionary k v) 
+    -- ^ A dictionary passed to observers. You populate
+    -- this dictionary with additional information describing
+    -- the notification. For distributed notifications, the
+    -- dictionary must contain only property list objects.
+
+  -> Bool 
+    -- ^ If True, the notification is delivered to all observers 
+    -- immediately, even if some observers are in suspended 
+    -- (background) applications and they requested different 
+    -- suspension behavior when registering for the notification. 
+    -- If False, each observer’s requested suspension behavior is respected.
+
+  -> IO ()
+postNotification = cfPostNotification
+
+{#fun CFNotificationCenterPostNotification as cfPostNotification
     { withObject* `NotificationCenter'
     , withObject* `String'
     , id `Ptr ()'
     , withMaybeObject* `Maybe (Dictionary k v)'
-    , id `CBoolean'
+    , `Bool'
     } -> `()' #}
 
 deriving instance Typeable NotificationCenter

CoreFoundation/System/CoreFoundation/Number.chs

@@ -1,14 +1,19 @@
 -- | 'Number' is a class which wraps basic C scalar (numeric) types.
 -- It is toll-free bridged with 'NSNumber'.
 module System.CoreFoundation.Number(
+                -- * Types
                 Number,
                 NumberRef,
+                -- * Converting to basic types
                 number,
                 value,
+                NumberType(..),
                 numberType,
                 IsNumberType,
-                NumberType(..),
                 isFloatType,
+                -- * Simple view
+                NumberView,
+                viewNumber,
                 ) where
 
 import Foreign.Ptr
@@ -56,7 +61,7 @@ declareCFType "Number"
     , kCFNumberCGFloatType as CGFloatType
     } deriving (Show,Eq) #}
 
--- Returns the type used by the 'Number' object to store its value. 
+-- | Returns the type used by the 'Number' object to store its value. 
 -- 
 -- The type specified by 'number' is not necessarily preserved when 
 -- a new 'Number' is created --- it uses whatever internal storage type
@@ -144,6 +149,7 @@ value n = unsafePerformIO $ alloca $ \p -> do
     , castPtr `Ptr a'
     } -> `NumberRef' id #}
 
+-- | Convert to a 'Number'.
 number :: forall a . IsNumberType a => a -> Number
 number n = unsafePerformIO $ with n $ \np -> getOwned $
                 cfNumberCreate (numberTypeOf (undefined :: a)) np