More documentation. soffes#24 soffes#25

SSToolkit/NSArray+SSToolkitAdditions.h

@@ -6,10 +6,30 @@
 //  Copyright 2009-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSArray` for various common tasks.
+ */
 @interface NSArray (SSToolkitAdditions)
 
+/**
+ Returns the object in the array with the lowest index value.
+ 
+ @return The object in the array with the lowest index value. If the array is empty, returns `nil`.
+ */
 - (id)firstObject;
+
+/**
+ Returns the object in the array with a random index value.
+ 
+ @return The object in the array with a random index value. If the array is empty, returns `nil`.
+ */
 - (id)randomObject;
+
+/**
+ Returns a new array with its elements shuffled.
+ 
+ @return A new array containing the receiving array's elements rearranged in a random order.
+ */
 - (NSArray *)shuffledArray;
 
 @end

SSToolkit/NSData+SSToolkitAdditions.h

@@ -6,8 +6,16 @@
 //  Copyright 2008-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSData` for various common tasks.
+ */
 @interface NSData (SSToolkitAdditions)
 
+/**
+ Returns a string of the MD5 sum of the receiver.
+ 
+ @return The string of the MD5 sum of the receiver.
+ */
 - (NSString *)MD5Sum;
 
 @end

SSToolkit/NSDate+SSToolkitAdditions.h

@@ -6,6 +6,9 @@
 //  Copyright 2010-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSDate` for various common tasks.
+ */
 @interface NSDate (SSToolkitAdditions)
 
 + (NSDate *)dateFromISO8601String:(NSString *)string;

SSToolkit/NSDictionary+SSToolkitAdditions.h

@@ -6,6 +6,9 @@
 //  Copyright 2010-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSDictionary` for various common tasks.
+ */
 @interface NSDictionary (SSToolkitAdditions)
 
 + (NSDictionary *)dictionaryWithFormEncodedString:(NSString *)encodedString;

SSToolkit/NSString+SSToolkitAdditions.h

@@ -6,6 +6,9 @@
 //  Copyright 2009-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSString` for various common tasks.
+ */
 @interface NSString (SSToolkitAdditions)
 
 - (BOOL)containsString:(NSString *)string;

SSToolkit/NSURL+SSToolkitAdditions.h

@@ -6,6 +6,9 @@
 //  Copyright 2010-2011 Sam Soffes. All rights reserved.
 //
 
+/**
+ Provides extensions to `NSURL` for various common tasks.
+ */
 @interface NSURL (SSToolkitAdditions)
 
 - (NSDictionary *)queryDictionary;

SSToolkit/SSAddressBarTextField.m

@@ -69,15 +69,15 @@ - (id)initWithFrame:(CGRect)aFrame {
 		UIButton *aReloadButton = [UIButton buttonWithType:UIButtonTypeCustom];
 		aReloadButton.contentHorizontalAlignment = UIControlContentHorizontalAlignmentRight;
 		aReloadButton.contentVerticalAlignment = UIControlContentVerticalAlignmentCenter;
-		[aReloadButton setImage:[UIImage imageNamed:@"SSAddressBarTextFieldReload.png" bundle:kSSToolkitBundleName] forState:UIControlStateNormal];
+		[aReloadButton setImage:[UIImage imageNamed:@"SSAddressBarTextFieldReload.png" bundleName:kSSToolkitBundleName] forState:UIControlStateNormal];
 		self.reloadButton = aReloadButton;
 		self.rightView = _reloadButton;
 
 		// Stop button
 		UIButton *aStopButton = [UIButton buttonWithType:UIButtonTypeCustom];
 		aStopButton.contentHorizontalAlignment = UIControlContentHorizontalAlignmentRight;
 		aStopButton.contentVerticalAlignment = UIControlContentVerticalAlignmentCenter;
-		[aStopButton setImage:[UIImage imageNamed:@"SSAddressBarTextFieldStop.png" bundle:kSSToolkitBundleName] forState:UIControlStateNormal];
+		[aStopButton setImage:[UIImage imageNamed:@"SSAddressBarTextFieldStop.png" bundleName:kSSToolkitBundleName] forState:UIControlStateNormal];
 		self.stopButton = aStopButton;
 
 		self.loading = NO;

SSToolkit/SSAddressBarTextFieldBackgroundViewInnerView.m

@@ -28,7 +28,7 @@ - (id)initWithFrame:(CGRect)aFrame {
 
 - (void)drawRect:(CGRect)rect {
 	CGSize size = self.frame.size;
-	[[UIImage imageNamed:@"SSAddressBarTextFieldBackground.png" bundle:kSSToolkitBundleName] drawAsPatternInRect:CGRectMake(0.0f, 0.0f, size.width, size.height)];
+	[[UIImage imageNamed:@"SSAddressBarTextFieldBackground.png" bundleName:kSSToolkitBundleName] drawAsPatternInRect:CGRectMake(0.0f, 0.0f, size.width, size.height)];
 }
 
 @end

SSToolkit/SSAnimatedImageView.h

@@ -8,7 +8,8 @@
 
 @protocol SSAnimatedImageViewDelegate;
 
-/** Animated image view.
+/**
+ Animated image view.
  
  `SSAnimatedImageView` is a simple subclass of `UIImageView` that provides more advanced control of image animations.
  The animation is backed by a `CAKeyframeAnimation`.
@@ -21,23 +22,31 @@
 /// @name Starting Animations
 ///--------------------------
 
-/** Start an image animation.
+/**
+ Start an image animation.
  
  @param animationName The named of the animation.
+ 
  @param images An array of `UIImage` objects that will be animated.
+ 
  @param delegate The delegate of the animation.
  
  The duration is set to the appropriate length for playing the images at 30fps.
  */
 - (void)startImageAnimation:(NSString *)animationName images:(NSArray *)images delegate:(id<SSAnimatedImageViewDelegate>)delegate;
 
 
-/** Start an image animation with duration and repeat count.
+/**
+ Start an image animation with duration and repeat count.
  
  @param animationName The named of the animation.
+ 
  @param images An array of `UIImage` objects that will be animated.
+ 
  @param duration The duration of the animation.
+ 
  @param repeatCount The number of times the animation repeats. Specify `0` to repeat indefinitely.
+ 
  @param delegate The delegate of the animation.
  */
 - (void)startImageAnimation:(NSString *)animationName images:(NSArray *)images duration:(NSTimeInterval)duration repeatCount:(NSUInteger)repeatCount delegate:(id<SSAnimatedImageViewDelegate>)delegate;
@@ -46,12 +55,17 @@
 /// @name Starting Timed Animations
 ///--------------------------------
 
-/** Start a timed image animation with repeat count.
+/**
+ Start a timed image animation with repeat count.
  
  @param animationName The named of the animation.
+ 
  @param images An array of `UIImage` objects that will be animated.
+ 
  @param keyTimes An array of `NSNumber` objects that define the duration of each keyframe segment.
+ 
  @param repeatCount The number of times the animation repeats. Specify `0` to repeat indefinitely.
+ 
  @param delegate The delegate of the animation.
  
  See `CAKeyframeAnimation`'s documentation for more information on how to specify `keyTimes`.
@@ -61,11 +75,38 @@
 @end
 
 
+/**
+ The `SSAnimatedImageViewDelegate` protocol defines methods that a delegate of a `SSAnimatedImageView` object can
+ optionally implement to observe the animation status.
+ 
+ @warning **Important:** Before releasing an instance of `SSAnimatedImageView` for which you have set a delegate, you
+ must first set the `SSAnimatedImageView` delegate property to `nil` before disposing of the `SSAnimatedImageView`
+ instance. This can be done, for example, in the `dealloc` method where you dispose of the `SSAnimatedImageView`.
+ */
 @protocol SSAnimatedImageViewDelegate <NSObject>
 
 @optional
 
-- (void)imageView:(SSAnimatedImageView *)imageView didStartAnimation:(NSString *)animationName;
-- (void)imageView:(SSAnimatedImageView *)imageView didFinishAnimation:(NSString *)animationName;
+/**
+ Sent when an image view begins playing its animation.
+ 
+ @param anImageView The image view that started playng its animation.
+ 
+ @param animationName The name of the animation that started.
+ 
+ @see imageView:didFinishAnimation:
+ */
+- (void)imageView:(SSAnimatedImageView *)anImageView didStartAnimation:(NSString *)animationName;
+
+/**
+ Sent after an image view finished playing its animation.
+ 
+ @param anImageView The image view that finished playng its animation.
+ 
+ @param animationName The name of the animation that started.
+ 
+ @see imageView:didStartAnimation:
+ */
+- (void)imageView:(SSAnimatedImageView *)anImageView didFinishAnimation:(NSString *)animationName;
 
 @end

SSToolkit/SSBadgeTableViewCell.h

@@ -8,15 +8,19 @@
 
 @class SSBadgeView;
 
-/// Table view cell that displays a `SSBadgeView` as its accessory.
+/**
+ Table view cell that displays a `SSBadgeView` as its accessory.
+ */
 @interface SSBadgeTableViewCell : UITableViewCell {
 
 @private
 
 	SSBadgeView *_badgeView;
 }
 
-/// A view that indicates some status to the user. (read-only)
+/**
+ A view that indicates some status to the user. (read-only)
+ */
 @property (nonatomic, retain, readonly) SSBadgeView *badgeView;
 
 @end

SSToolkit/SSBadgeView.h

@@ -14,7 +14,8 @@ typedef enum {
 
 @class SSLabel;
 
-/** Badge view.
+/**
+ Badge view.
  
  Provides the accesory view for a SSBadgeTableViewCell, available through the `badgeView` property.
  
@@ -41,42 +42,49 @@ typedef enum {
 /// @name Accessing the Badge Label
 ///--------------------------------
 
-/// The badge text label.
+/**
+ The badge text label.
+ */
 @property (nonatomic, retain, readonly) SSLabel *textLabel;
 
 ///-------------------------------------
 /// @name Accessing the Badge Attributes
 ///-------------------------------------
 
-/** The badge's background color.
+/**
+ The badge's background color.
  
  The default value of this property is grayish blue (that matches Mail.app).
  
  @see defaultBadgeColor
  */
 @property (nonatomic, retain) UIColor *badgeColor;
 
-/** The badge's background color while its cell is highlighted.
+/**
+ The badge's background color while its cell is highlighted.
  
  The default value of this property is white.
  */
 @property (nonatomic, retain) UIColor *highlightedBadgeColor;
 
-/** The corner radius used when rendering the badge's outline.
+/**
+ The corner radius used when rendering the badge's outline.
  
  The default value of this property is 10.
  */
 @property (nonatomic, assign) CGFloat cornerRadius;
 
-/** The badge's horizontal alignment within the accesoryView frame.
+/**
+ The badge's horizontal alignment within the accesoryView frame.
  
  This will position the badge in the view's bounds accordinly.
  
  The default value of this property is `SSBadgeViewAlignmentCenter`.
  */
 @property (nonatomic, assign) SSBadgeViewAlignment badgeAlignment;
 
-/** A Boolean value indicating whether the receiver should be drawn with a highlight.
+/**
+ A Boolean value indicating whether the receiver should be drawn with a highlight.
  
  Setting this property causes the receiver to redraw with the appropriate highlight state.
  
@@ -88,15 +96,17 @@ typedef enum {
 /// @name Drawing Images
 ///---------------------
 
-/** The badge's background image.
+/**
+ The badge's background image.
  
  The default value of this property is `nil`. If the value is non-nil, it will be draw instead of the color.
  
  Setting a strechable image for this property is recommended.
  */
 @property (nonatomic, retain) UIImage *badgeImage;
 
-/** The badge's background image while its cell is highlighted.
+/**
+ The badge's background image while its cell is highlighted.
  
  The default value of this property is `nil`. If the value is non-nil, it will be draw instead of the color.
  
@@ -108,7 +118,8 @@ typedef enum {
 /// @name Defaults
 ///---------------
 
-/** The default badge color.
+/**
+ The default badge color.
  
  @return A color with its value set to the default badge color.
  */

SSToolkit/SSBordererView.h

@@ -6,7 +6,9 @@
 //  Copyright 2011 Sam Soffes. All rights reserved.
 //
 
-/// Simple UIView for drawing top and bottom borders with optional insets in a view.
+/**
+ Simple UIView for drawing top and bottom borders with optional insets in a view.
+ */
 @interface SSBordererView : UIView {
 
 @private
@@ -21,13 +23,15 @@
 /// @name Drawing the Top Border
 ///-----------------------------
 
-/** The top border color. The default is `nil`.
+/**
+ The top border color. The default is `nil`.
  
  @see bottomBorderColor
  */
 @property (nonatomic, retain) UIColor *topBorderColor;
 
-/** The top inset color. The default is `nil`.
+/**
+ The top inset color. The default is `nil`.
  
  @see bottomInsetColor
  */
@@ -37,13 +41,15 @@
 /// @name Drawing the Bottom Border
 ///--------------------------------
 
-/** The bottom inset color. The default is `nil`.
+/**
+ The bottom inset color. The default is `nil`.
  
  @see topInsetColor
  */
 @property (nonatomic, retain) UIColor *bottomInsetColor;
 
-/** The bottom border color. The default is `nil`.
+/**
+ The bottom border color. The default is `nil`.
  
  @see topBorderColor
  */