Added comments explaining cache policy options

@@ -9,17 +9,40 @@
 #import <Foundation/Foundation.h>
 #import <Foundation/Foundation.h>
 @class ASIHTTPRequest;
 @class ASIHTTPRequest;
 
 
+// Cache policies control the behaviour of a cache and how requests use the cache
+// When setting a cache policy, you can use a combination of these values as a bitmask
+// For example: [request setCachePolicy:ASIAskServerIfModifiedCachePolicy|ASIFallbackToCacheIfLoadFailsCachePolicy|ASIDoNotWriteToCacheCachePolicy];
+// Note that some of the behaviours below are mutally exclusive - you cannot combine ASIAskServerIfModifiedWhenStaleCachePolicy and ASIAskServerIfModifiedCachePolicy, for example.
 typedef enum _ASICachePolicy {
 typedef enum _ASICachePolicy {
+
+	// The default cache policy. When you set a request to use this, it will use the cache's defaultCachePolicy
+	// ASIDownloadCache's default cache policy is 'ASIAskServerIfModifiedWhenStaleCachePolicy'
 	ASIUseDefaultCachePolicy = 0,
 	ASIUseDefaultCachePolicy = 0,
+
+	// Tell the request not to read from the cache
 	ASIDoNotReadFromCacheCachePolicy = 1,
 	ASIDoNotReadFromCacheCachePolicy = 1,
+
+	// The the request not to write to the cache
 	ASIDoNotWriteToCacheCachePolicy = 2,
 	ASIDoNotWriteToCacheCachePolicy = 2,
+
+	// Ask the server if there is an updated version of this resource (using a conditional GET) ONLY when the cached data is stale
 	ASIAskServerIfModifiedWhenStaleCachePolicy = 4,
 	ASIAskServerIfModifiedWhenStaleCachePolicy = 4,
+
+	// Always ask the server if there is an updated version of this resource (using a conditional GET)
 	ASIAskServerIfModifiedCachePolicy = 8,
 	ASIAskServerIfModifiedCachePolicy = 8,
+
+	// If cached data exists, use it even if it is stale. This means requests will not talk to the server unless the resource they are requesting is not in the cache
 	ASIOnlyLoadIfNotCachedCachePolicy = 16,
 	ASIOnlyLoadIfNotCachedCachePolicy = 16,
+
+	// If cached data exists, use it even if it is stale. If cached data does not exist, stop (will not set an error on the request)
 	ASIDontLoadCachePolicy = 32,
 	ASIDontLoadCachePolicy = 32,
+
+	// Specifies that cached data may be used if the request fails. If cached data is used, the request will succeed without error. Usually used in combination with other options above.
 	ASIFallbackToCacheIfLoadFailsCachePolicy = 64
 	ASIFallbackToCacheIfLoadFailsCachePolicy = 64
 } ASICachePolicy;
 } ASICachePolicy;
 
 
+// Cache storage policies control whether cached data persists between application launches (ASICachePermanentlyCacheStoragePolicy) or not (ASICachePermanentlyCacheStoragePolicy)
+// Calling [ASIHTTPRequest clearSession] will remove any data stored using ASICacheForSessionDurationCacheStoragePolicy
 typedef enum _ASICacheStoragePolicy {
 typedef enum _ASICacheStoragePolicy {
 	ASICacheForSessionDurationCacheStoragePolicy = 0,
 	ASICacheForSessionDurationCacheStoragePolicy = 0,
 	ASICachePermanentlyCacheStoragePolicy = 1
 	ASICachePermanentlyCacheStoragePolicy = 1