Permalink
Browse files

[core] Fully clean up the core documentation by moving all class meth…

…od docs to the bottom of the files.
  • Loading branch information...
1 parent c24cf64 commit a808c78cd9af24841ce43a8c2568f06150ff428c @jverkoey jverkoey committed Aug 4, 2011
@@ -314,7 +314,7 @@ typedef void NILinkedListLocation;
*/
-#pragma mark Creating a Linked List /** @name Creating a Linked List */
+/** @name Creating a Linked List */
/**
* Convenience method for creating an autoreleased linked list.
@@ -342,7 +342,7 @@ typedef void NILinkedListLocation;
*/
-#pragma mark Querying a Linked List /** @name Querying a Linked List */
+/** @name Querying a Linked List */
/**
* Returns the number of objects currently in the linked list.
@@ -401,7 +401,7 @@ typedef void NILinkedListLocation;
*/
-#pragma mark Adding Objects /** @name Adding Objects */
+/** @name Adding Objects */
/**
* Append an object to the linked list.
@@ -413,7 +413,7 @@ typedef void NILinkedListLocation;
*/
-#pragma mark Removing Objects /** @name Removing Objects */
+/** @name Removing Objects */
/**
* Remove all objects from the linked list.
@@ -448,7 +448,7 @@ typedef void NILinkedListLocation;
*/
-#pragma mark Constant-Time Access /** @name Constant-Time Access */
+/** @name Constant-Time Access */
/**
* Search for an object in the linked list.
@@ -44,116 +44,191 @@
NILinkedList* _lruCacheObjects;
}
-#pragma mark Creating an In-Memory Cache /** @name Creating an In-Memory Cache */
+// Designated initializer.
+- (id)initWithCapacity:(NSUInteger)capacity;
+
+- (NSUInteger)count;
+
+- (void)storeObject:(id)object withName:(NSString *)name;
+- (void)storeObject:(id)object withName:(NSString *)name expiresAfter:(NSDate *)expirationDate;
+
+- (void)removeObjectWithName:(NSString *)name;
+- (void)removeAllObjects;
+
+- (id)objectWithName:(NSString *)name;
+- (BOOL)containsObjectWithName:(NSString *)name;
+- (NSDate *)dateOfLastAccessWithName:(NSString *)name;
+
+- (void)reduceMemoryUsage;
+
+
+// Subclassing
+
+- (void)willSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
+- (void)didSetObject:(id)object withName:(NSString *)name;
+- (void)willRemoveObject:(id)object withName:(NSString *)name;
+
+@end
+
/**
- * Initialize the cache with zero initial capacity.
+ * An in-memory cache for storing images with caps on the total number of pixels.
+ *
+ * When reduceMemoryUsage is called, the least recently used images are removed from the cache
+ * until the numberOfPixels is below maxNumberOfPixelsUnderStress.
+ *
+ * When an image is added to the cache that causes the memory usage to pass the max, the
+ * least recently used images are removed from the cache until the numberOfPixels is below
+ * maxNumberOfPixels.
+ *
+ * By default the image memory cache has no limit to its pixel count. You must explicitly
+ * set this value in your application.
+ *
+ * @attention If the cache is too small to fit the newly added image, then all images
+ * will end up being removed including the one being added.
+ *
+ * @see Nimbus::imageMemoryCache
+ * @see Nimbus::setImageMemoryCache:
*/
-- (id)init;
+@interface NIImageMemoryCache : NIMemoryCache {
+@private
+ NSUInteger _numberOfPixels;
+
+ NSUInteger _maxNumberOfPixels;
+ NSUInteger _maxNumberOfPixelsUnderStress;
+}
+
+@property (nonatomic, readonly, assign) NSUInteger numberOfPixels;
+@property (nonatomic, readwrite, assign) NSUInteger maxNumberOfPixels;
+@property (nonatomic, readwrite, assign) NSUInteger maxNumberOfPixelsUnderStress;
+
+@end
+
+
+///////////////////////////////////////////////////////////////////////////////////////////////////
+/**@}*/// End of In-Memory Cache //////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////////////////////////
+
+
+/** @name Creating an In-Memory Cache */
/**
- * Designated initializer. Initialize the cache with an initial capacity.
+ * Initializes a newly allocated cache with the given capacity.
*
- * Use a best guess to avoid having the internal data structure reallocate its memory repeatedly
- * - at least up up to a certain point - as the cache grows.
+ * @returns An in-memory cache initialized with the given capacity.
+ * @fn NIMemoryCache::initWithCapacity:
*/
-- (id)initWithCapacity:(NSUInteger)capacity;
-#pragma mark Storing Objects in the Cache /** @name Storing Objects in the Cache */
+/** @name Storing Objects in the Cache */
/**
- * Store an object in the cache.
- *
- * @param object The object being stored in the cache.
- * @param name The name used as a key to store this object.
+ * Stores an object in the cache.
*
* The object will be stored without an expiration date. The object will stay in the cache until
* it's bumped out due to the cache's memory limit.
+ *
+ * @param object The object being stored in the cache.
+ * @param name The name used as a key to store this object.
+ * @fn NIMemoryCache::storeObject:withName:
*/
-- (void)storeObject:(id)object withName:(NSString *)name;
/**
- * Store an object in the cache with an expiration date.
- *
- * @param object The object being stored in the cache.
- * @param name The name used as a key to store this object.
- * @param expirationDate A date after which this object is no longer valid in the cache.
+ * Stores an object in the cache with an expiration date.
*
* If an object is stored with an expiration date that has already passed then the object will
* not be stored in the cache and any existing object will be removed. The rationale behind this
* is that the object would be removed from the cache the next time it was accessed anyway.
+ *
+ * @param object The object being stored in the cache.
+ * @param name The name used as a key to store this object.
+ * @param expirationDate A date after which this object is no longer valid in the cache.
+ * @fn NIMemoryCache::storeObject:withName:expiresAfter:
*/
-- (void)storeObject:(id)object withName:(NSString *)name expiresAfter:(NSDate *)expirationDate;
-#pragma mark Removing Objects from the Cache /** @name Removing Objects from the Cache */
+/** @name Removing Objects from the Cache */
/**
- * Remove an object in the cache.
+ * Removes an object from the cache.
*
* @param name The name used as a key to store this object.
+ * @fn NIMemoryCache::removeObjectWithName:
*/
-- (void)removeObjectWithName:(NSString *)name;
/**
- * Remove all objects from the cache, regardless of expiration dates.
+ * Removes all objects from the cache, regardless of expiration dates.
*
* This will completely clear out the cache and all objects in the cache will be released.
+ *
+ * @fn NIMemoryCache::removeAllObjects
*/
-- (void)removeAllObjects;
-#pragma mark Accessing Objects in the Cache /** @name Accessing Objects in the Cache */
+/** @name Accessing Objects in the Cache */
/**
- * Retrieve an object from the cache.
+ * Retrieves an object from the cache.
*
* If the object has expired then the object will be removed from the cache and nil will be
* returned.
+ *
+ * @returns The object stored in the cache. The object is retained and autoreleased to
+ * ensure that it survives this run loop if you then remove it from the cache.
+ * @fn NIMemoryCache::objectWithName:
*/
-- (id)objectWithName:(NSString *)name;
/**
- * Determine whether an object is in the cache or not without modifying the access time.
+ * Returns a Boolean value that indicates whether an object with the given name is present
+ * in the cache.
*
- * This is useful if you simply want to check the cache for the existence of an object.
+ * Does not update the access time of the object.
*
- * If the object has expired then the object will be removed from the cache and nil will be
+ * If the object has expired then the object will be removed from the cache and NO will be
* returned.
+ *
+ * @returns YES if an object with the given name is present in the cache and has not expired,
+ * otherwise NO.
+ * @fn NIMemoryCache::containsObjectWithName:
*/
-- (BOOL)hasObjectWithName:(NSString *)name;
/**
- * Retrieve the data that the object with the given name was last accessed.
+ * Returns the date that the object with the given name was last accessed.
*
- * This will not update the access time of the object.
+ * Does not update the access time of the object.
*
* If the object has expired then the object will be removed from the cache and nil will be
* returned.
+ *
+ * @returns The last access date of the object if it exists and has not expired, nil
+ * otherwise.
+ * @fn NIMemoryCache::dateOfLastAccessWithName:
*/
-- (NSDate *)dateOfLastAccessWithName:(NSString *)name;
-#pragma mark Reducing Memory Usage Explicitly /** @name Reducing Memory Usage Explicitly */
+/** @name Reducing Memory Usage Explicitly */
/**
- * Remove all expired objects from the cache.
+ * Removes all expired objects from the cache.
+ *
+ * Subclasses may add additional functionality to this implementation.
+ * Subclasses should call super in order to prune expired objects.
*
- * Subclasses may add additional functionality to this implementation and should generally
- * call super.
+ * This will be called when <code>UIApplicationDidReceiveMemoryWarningNotification</code>
+ * is posted.
*
- * This will be called when UIApplicationDidReceiveMemoryWarningNotification is posted.
+ * @fn NIMemoryCache::reduceMemoryUsage
*/
-- (void)reduceMemoryUsage;
-#pragma mark Querying an In-Memory Cache /** @name Querying an In-Memory Cache */
+/** @name Querying an In-Memory Cache */
/**
- * The number of objects stored in this cache.
+ * Returns the number of objects currently in the cache.
+ *
+ * @returns The number of objects currently in the cache.
+ * @fn NIMemoryCache::count
*/
-@property (nonatomic, readonly) NSUInteger count;
/**
@@ -162,92 +237,64 @@
* The following methods are provided to aid in subclassing and are not meant to be
* used externally.
*/
-#pragma mark Subclassing
/**
* An object is about to be stored in the cache.
*
- * @param object The object to be stored in the cache.
+ * @param object The object that is about to be stored in the cache.
* @param name The cache name for the object.
* @param previousObject The object previously stored in the cache. This may be the
* same as object.
+ * @fn NIMemoryCache::willSetObject:withName:previousObject:
*/
-- (void)willSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
/**
* An object has been stored in the cache.
*
* @param object The object that was stored in the cache.
* @param name The cache name for the object.
+ * @fn NIMemoryCache::didSetObject:withName:
*/
-- (void)didSetObject:(id)object withName:(NSString *)name;
/**
* An object is about to be removed from the cache.
*
* @param object The object about to removed from the cache.
* @param name The cache name for the object about to be removed.
+ * @fn NIMemoryCache::willRemoveObject:withName:
*/
-- (void)willRemoveObject:(id)object withName:(NSString *)name;
-
-@end
-/**
- * An in-memory cache for storing images with caps on the total number of pixels.
- *
- * When reduceMemoryUsage is called, the least recently used images are removed from the cache
- * until the numberOfPixels is below maxNumberOfPixelsUnderStress.
- *
- * When an image is added to the cache that causes the memory usage to pass the max, the
- * least recently used images are removed from the cache until the numberOfPixels is below
- * maxNumberOfPixels.
- *
- * By default the image memory cache has no limit to its pixel count. You must explicitly
- * set this value in your application.
- *
- * @attention If the cache is too small to fit the newly added image, then all images
- * will end up being removed including the one being added.
- *
- * @see Nimbus::imageMemoryCache
- * @see Nimbus::setImageMemoryCache:
- */
-@interface NIImageMemoryCache : NIMemoryCache {
-@private
- NSUInteger _numberOfPixels;
-
- NSUInteger _maxNumberOfPixels;
- NSUInteger _maxNumberOfPixelsUnderStress;
-}
-
+///////////////////////////////////////////////////////////////////////////////////////////////////
+// NIImageMemoryCache
-#pragma mark Querying an In-Memory Image Cache /** @name Querying an In-Memory Image Cache */
+/** @name Querying an In-Memory Image Cache */
/**
- * The total number of pixels being stored in the cache.
+ * Returns the total number of pixels being stored in the cache.
+ *
+ * @returns The total number of pixels being stored in the cache.
+ * @fn NIImageMemoryCache::numberOfPixels
*/
-@property (nonatomic, readonly, assign) NSUInteger numberOfPixels;
-#pragma mark Setting the Maximum Number of Pixels /** @name Setting the Maximum Number of Pixels */
+/** @name Setting the Maximum Number of Pixels */
/**
* The maximum number of pixels this cache may ever store.
*
* Defaults to 0, which is special cased to represent an unlimited number of pixels.
+ *
+ * @returns The maximum number of pixels this cache may ever store.
+ * @fn NIImageMemoryCache::maxNumberOfPixels
*/
-@property (nonatomic, readwrite, assign) NSUInteger maxNumberOfPixels;
/**
* The maximum number of pixels this cache may store after a call to reduceMemoryUsage.
*
* Defaults to 0, which is special cased to represent an unlimited number of pixels.
+ *
+ * @returns The maximum number of pixels this cache may store after a call
+ * to reduceMemoryUsage.
+ * @fn NIImageMemoryCache::maxNumberOfPixelsUnderStress
*/
-@property (nonatomic, readwrite, assign) NSUInteger maxNumberOfPixelsUnderStress;
-
-@end
-
-
-///////////////////////////////////////////////////////////////////////////////////////////////////
-/**@}*/// End of In-Memory Cache //////////////////////////////////////////////////////////////////
-///////////////////////////////////////////////////////////////////////////////////////////////////
Oops, something went wrong.

0 comments on commit a808c78

Please sign in to comment.