Update documentation

Author: Michael Potter

FastImageCache/FICImageCache.h

@@ -41,10 +41,24 @@ typedef void (^FICImageRequestCompletionBlock)(UIImage *sourceImage);
 ///---------------------------------------
 
 /**
- Convenience accessor to retrieve a shared image cache instance.
+ Returns the shared image cache.
+ 
+ @return A shared instance of `FICImageCache`.
+ 
+ @note Fast Image Cache can either be used as a singleton for convenience or can exist as multiple instances. However, all instances of `FICImageCache` will make use of
+ shared resources, such as the same dispatch queue and the same location on disk for storing image tables.
+ 
+ @see [FICImageCache dispatchQueue]
  */
 + (instancetype)sharedImageCache;
 
+/**
+ Returns the shared dispatch queue used by all instances of `FICImageCache`.
+ 
+ @return A generic, shared dispatch queue of type `dispatch_queue_t`.
+ 
+ @note All instances of `FICImageCache` make use a single, shared dispatch queue to do their work.
+ */
 + (dispatch_queue_t)dispatchQueue;
 
 ///---------------------------------

FastImageCache/FICImageFormat.h

@@ -15,14 +15,14 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatDevices) {
     FICImageFormatDevicePad = 1 << UIUserInterfaceIdiomPad,
 };
 
-typedef NS_OPTIONS(NSUInteger, FICImageFormatStyle) {
+typedef NS_ENUM(NSUInteger, FICImageFormatStyle) {
     FICImageFormatStyle32BitBGRA,
     FICImageFormatStyle32BitBGR,
     FICImageFormatStyle16BitBGR,
     FICImageFormatStyle8BitGrayscale,
 };
 
-typedef NS_OPTIONS(NSUInteger, FICImageFormatProtectionMode) {
+typedef NS_ENUM(NSUInteger, FICImageFormatProtectionMode) {
     FICImageFormatProtectionModeNone,
     FICImageFormatProtectionModeComplete,
     FICImageFormatProtectionModeCompleteUntilFirstUserAuthentication,
@@ -42,6 +42,9 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatProtectionMode) {
 
 /**
  The name of the image format. Each image format must have a unique name.
+ 
+ @note Since multiple instances of Fast Image Cache can exist in the same application, it is important that image format name's be unique across all instances of `<FICImageCache>`. Reverse DNS naming
+ is recommended (e.g., com.path.PTUserProfilePhotoLargeImageFormat).
  */
 @property (nonatomic, copy) NSString *name;
 
@@ -120,14 +123,34 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatProtectionMode) {
  */
 @property (nonatomic, assign, readonly) BOOL isGrayscale;
 
-
+/**
+ The data protection mode that image table files will be created with.
+ 
+ `FICImageFormatProtectionMode` has the following values:
+ 
+ - `FICImageFormatProtectionModeNone`: No data protection is used. The image table file backing this image format will always be available for reading and writing.
+ - `FICImageFormatProtectionModeComplete`: Complete data protection is used. As soon as the system enables data protection (i.e., when the device is locked), the image table file backing this image
+ format will not be available for reading and writing. As a result, images of this format should not be requested by Fast Image Cache when executing backgrounded code.
+ - `FICImageFormatProtectionModeCompleteUntilFirstUserAuthentication`: Partial data protection is used. After a device restart, until the user unlocks the device for the first time, complete data
+ protection is in effect. However, after the device has been unlocked for the first time, the image table file backing this image format will remain available for readin and writing. This mode may be
+ a good compromise between encrypting image table files after the device powers down and allowing the files to be accessed successfully by Fast Image Cache, whether or not the device is subsequently
+ locked.
+ 
+ @note Data protection can prevent Fast Image Cache from accessing its image table files to read and write image data. If the image data being stored in Fast Image Cache is not sensitive in nature,
+ consider using `FICImageFormatProtectionModeNone` to prevent any issues accessing image table files when the disk is encrypted.
+ */
 @property (nonatomic, assign) FICImageFormatProtectionMode protectionMode;
+
+/**
+ The string representation of `<protectionMode>`.
+ */
 @property (nonatomic, assign, readonly) NSString *protectionModeString;
 
 /**
  The dictionary representation of this image format.
  
- @discussion Fast Image Cache automatically serializes the image formats that it uses to disk. If an image format ever changes, Fast Image Cache automatically detects the change and invalidates the image table associated with that image format. The image table is then recreated from the updated image format.
+ @discussion Fast Image Cache automatically serializes the image formats that it uses to disk. If an image format ever changes, Fast Image Cache automatically detects the change and invalidates the
+ image table associated with that image format. The image table is then recreated from the updated image format.
  */
 @property (nonatomic, copy, readonly) NSDictionary *dictionaryRepresentation;
 
@@ -150,7 +173,9 @@ typedef NS_OPTIONS(NSUInteger, FICImageFormatProtectionMode) {
  
  @param devices A bitmask of type `<FICImageFormatDevices>` that defines which devices are managed by an image table.
  
- @return An autoreleased instance of `<FICImageFormat>` or one of its subclasses, if any exist.
+ @param protectionMode The data protection mode to use when creating the backing image table file for this image format. See the `<protectionMode>` property description for more information.
+ 
+ @return An autoreleased instance of `FICImageFormat` or one of its subclasses, if any exist.
  */
 + (instancetype)formatWithName:(NSString *)name family:(NSString *)family imageSize:(CGSize)imageSize style:(FICImageFormatStyle)style maximumCount:(NSInteger)maximumCount devices:(FICImageFormatDevices)devices protectionMode:(FICImageFormatProtectionMode)protectionMode;
 

FastImageCache/FICImageTable.h

@@ -75,6 +75,8 @@ extern NSString *const FICImageTableScreenScaleKey;
  
  @param imageFormat The image format that describes the image table.
  
+ @param imageCache The instance of `<FICImageCache>` that owns this image table.
+ 
  @return A new image table.
  
  @warning `FICImageTable` raises an exception if `imageFormat` is `nil`. `FICImageTable`'s implementation of `-init` simply calls through to this initializer, passing `nil` for `imageFormat`.
@@ -110,11 +112,13 @@ extern NSString *const FICImageTableScreenScaleKey;
  
  @param sourceImageUUID The UUID of the source image that represents the actual image data stored in an image table entry. Must not be `nil`.
  
+ @param preheatData A `BOOL` indicating whether or not the entry's image data should be preheated. See `<[FICImageTableEntry preheat]>` for more information.
+ 
  @return A new image created from the entry data stored in the image table or `nil` if something went wrong.
  
  @discussion The `UIImage` returned by this method is initialized by a `CGImageRef` backed directly by mapped file data, so no memory copy occurs.
  
- @note If either of the parameters to this method are `nil`, the return value is `nil`.
+ @note If either of the first two parameters to this method are `nil`, the return value is `nil`.
  
  @note If either the entity UUID or the source image UUID doesn't match the corresponding UUIDs in the entry data, then something has changed. The entry data is deleted for the
  provided entity UUID, and `nil` is returned.

FastImageCache/FICImageTable.m

@@ -66,7 +66,9 @@ @interface FICImageTable () {
     NSString *_fileDataProtectionMode;
     BOOL _canAccessData;
 }
-@property(nonatomic, weak) FICImageCache *imageCache;
+
+@property (nonatomic, weak) FICImageCache *imageCache;
+
 @end
 
 #pragma mark

FastImageCache/FICImageTableChunk.h

@@ -36,6 +36,9 @@
  */
 @property (nonatomic, assign, readonly) off_t fileOffset;
 
+/**
+ The length, in bytes, of the chunk.
+ */
 @property (nonatomic, assign, readonly) size_t length;
 
 

FastImageCache/FICImageTableEntry.h

@@ -53,17 +53,24 @@ typedef struct {
  */
 @property (nonatomic, assign) CFUUIDBytes sourceImageUUIDBytes;
 
+/**
+ The image table chunk that contains this entry.
+ */
 @property (nonatomic, readonly) FICImageTableChunk *imageTableChunk;
 
+/**
+ A weak reference to the image cache that contains the image table chunk that contains this entry.
+ */
 @property (nonatomic, weak) FICImageCache *imageCache;
 
+/**
+ The index where this entry exists in the image table.
+ */
 @property (nonatomic, assign) NSInteger index;
 
-- (void)preheat;
-
-///----------------------------------------
-/// @name Initializing an Image Table Entry
-///----------------------------------------
+///----------------------------------
+/// @name Image Table Entry Lifecycle
+///----------------------------------
 
 /**
  Initializes a new image table entry from an image table chunk.
@@ -78,8 +85,20 @@ typedef struct {
  */
 - (instancetype)initWithImageTableChunk:(FICImageTableChunk *)imageTableChunk bytes:(void *)bytes length:(size_t)length;
 
+/**
+ Adds a block to be executed when this image table entry is deallocated.
+ 
+ @param block A block that will be called when this image table entry is deallocated.
+ 
+ @note Because of the highly-concurrent nature of Fast Image Cache, image tables must know when any of their entries are about to be deallocated to disassociate them with its internal data structures.
+ */
 - (void)executeBlockOnDealloc:(dispatch_block_t)block;
 
+/**
+ Forces the kernel to page in the memory-mapped, on-disk data backing this entry right away.
+ */
+- (void)preheat;
+
 ///--------------------------------------------
 /// @name Flushing a Modified Image Table Entry
 ///--------------------------------------------

FastImageCacheDemo/Classes/FICDPhoto.m

@@ -13,11 +13,11 @@
 
 NSString *const FICDPhotoImageFormatFamily = @"FICDPhotoImageFormatFamily";
 
-NSString *const FICDPhotoSquareImage32BitBGRAFormatName = @"FICDPhotoSquareImage32BitBGRAFormatName";
-NSString *const FICDPhotoSquareImage32BitBGRFormatName = @"FICDPhotoSquareImage32BitBGRFormatName";
-NSString *const FICDPhotoSquareImage16BitBGRFormatName = @"FICDPhotoSquareImage16BitBGRFormatName";
-NSString *const FICDPhotoSquareImage8BitGrayscaleFormatName = @"FICDPhotoSquareImage8BitGrayscaleFormatName";
-NSString *const FICDPhotoPixelImageFormatName = @"FICDPhotoPixelImageFormatName";
+NSString *const FICDPhotoSquareImage32BitBGRAFormatName = @"com.path.FastImageCacheDemo.FICDPhotoSquareImage32BitBGRAFormatName";
+NSString *const FICDPhotoSquareImage32BitBGRFormatName = @"com.path.FastImageCacheDemo.FICDPhotoSquareImage32BitBGRFormatName";
+NSString *const FICDPhotoSquareImage16BitBGRFormatName = @"com.path.FastImageCacheDemo.FICDPhotoSquareImage16BitBGRFormatName";
+NSString *const FICDPhotoSquareImage8BitGrayscaleFormatName = @"com.path.FastImageCacheDemo.FICDPhotoSquareImage8BitGrayscaleFormatName";
+NSString *const FICDPhotoPixelImageFormatName = @"com.path.FastImageCacheDemo.FICDPhotoPixelImageFormatName";
 
 CGSize const FICDPhotoSquareImageSize = {75, 75};
 CGSize const FICDPhotoPixelImageSize = {1, 1};