More documentation

SSPullToRefresh.h

@@ -6,6 +6,11 @@
 //  Copyright (c) 2012 Sam Soffes. All rights reserved.
 //
 
+// Main pull to refresh view. This class contains all of the pulling logic.
 #import "SSPullToRefreshView.h"
+
+// Default content view. Similar to Facebook.
 #import "SSPullToRefreshDefaultContentView.h"
+
+// Simple content view. Similar to Path.
 #import "SSPullToRefreshSimpleContentView.h"

SSPullToRefreshView.h

@@ -47,11 +47,11 @@ typedef enum {
 
 @interface SSPullToRefreshView : UIView
 
-@property (nonatomic, assign, readonly) UIScrollView *scrollView;
-@property (nonatomic, assign) id<SSPullToRefreshViewDelegate> delegate;
-@property (nonatomic, assign, readonly) SSPullToRefreshViewState state;
-@property (nonatomic, assign) CGFloat expandedHeight;
-@property (nonatomic, assign, readonly, getter = isExpanded) BOOL expanded;
+/**
+ The content view displayed when the `scrollView` is pulled down. By default this is an instance of `SSPullToRefreshDefaultContentView`.
+ 
+ @see SSPullToRefreshContentView
+ */
 @property (nonatomic, strong) UIView<SSPullToRefreshContentView> *contentView;
 
 /**
@@ -61,9 +61,54 @@ typedef enum {
  */
 @property (nonatomic, assign) UIEdgeInsets defaultContentInset;
 
+/**
+ The height of the fully expanded content view. The default is `70.0`.
+ 
+ The `contentView`'s `sizeThatFits:` will be respected when displayed but does not effect the expanded height. You can use this
+ to draw outside of the expanded area. If you don't implement `sizeThatFits:` it will automatically display at the default size.
+ 
+ @see expanded
+ */
+@property (nonatomic, assign) CGFloat expandedHeight;
+
+/**
+ A boolean indicating if the pull to refresh view is expanded.
+ 
+ @see expandedHeight
+ @see startLoadingAndExpand:
+ */
+@property (nonatomic, assign, readonly, getter = isExpanded) BOOL expanded;
+
+/**
+ The scroll view containing the pull to refresh view. This is automatically set with `initWithScrollView:delegate:`.
+ 
+ @see initWithScrollView:delegate:
+ */
+@property (nonatomic, assign, readonly) UIScrollView *scrollView;
+
+/**
+ The delegate is sent messages when the pull to refresh view starts loading. This is automatically set with `initWithScrollView:delegate:`.
+ 
+ @see initWithScrollView:delegate:
+ @see SSPullToRefreshViewDelegate
+ */
+@property (nonatomic, assign) id<SSPullToRefreshViewDelegate> delegate;
+
+/**
+ The state of the pull to refresh view.
+ 
+ @see startLoading
+ @see startLoadingAndExpand:
+ @see finishLoading
+ @see SSPullToRefreshViewState
+ */
+@property (nonatomic, assign, readonly) SSPullToRefreshViewState state;
+
 /**
  All you need to do to add this view to your scroll view is call this method (passing in the scroll view). That's it.
  You don't have to add it as subview or anything else. The rest is magic.
+ 
+ You should only initalize with this method and never move it to another scroll view during its lifetime.
  */
 - (id)initWithScrollView:(UIScrollView *)scrollView delegate:(id<SSPullToRefreshViewDelegate>)delegate;
 
@@ -86,6 +131,9 @@ typedef enum {
  */
 - (void)finishLoading;
 
+/**
+ Manually update the last updated at time. This will automatically get called when the pull to refresh view finishes laoding.
+ */
 - (void)refreshLastUpdatedAt;
 
 @end
@@ -95,9 +143,25 @@ typedef enum {
 
 @optional
 
+/**
+ Return `NO` if the pull to refresh view should no start loading.
+ */
 - (BOOL)pullToRefreshViewShouldStartLoading:(SSPullToRefreshView *)view;
+
+/**
+ The pull to refresh view started loading. You should kick off whatever you need to load when this is called.
+ */
 - (void)pullToRefreshViewDidStartLoading:(SSPullToRefreshView *)view;
+
+/**
+ The pull to refresh view finished loading. This will get called when it receives `finishLoading`.
+ */
 - (void)pullToRefreshViewDidFinishLoading:(SSPullToRefreshView *)view;
+
+/**
+ The date when data was last updated. This will get called when it finishes loading or if it receives `refreshLastUpdatedAt`.
+ Some content views may display this date.
+ */
 - (NSDate *)pullToRefreshViewLastUpdatedAt:(SSPullToRefreshView *)view;
 
 @end
@@ -107,12 +171,24 @@ typedef enum {
 
 @required
 
+/**
+ The pull to refresh view's state has changed. The content view must update itself. All content view's must implement
+ this method.
+ */
 - (void)setState:(SSPullToRefreshViewState)state withPullToRefreshView:(SSPullToRefreshView *)view;
 
 @optional
 
-- (CGSize)contentSize;
+/**
+ The pull to refresh view will set send values from `0.0` to `1.0` as the user pulls down. `1.0` means it is fully expanded and
+ will change to the `SSPullToRefreshViewStateReady` state. You can use this value to draw the progress of the pull
+ (i.e. Tweetbot style).
+ */
 - (void)setPullProgress:(CGFloat)pullProgress;
+
+/**
+ The pull to refresh view updated its last updated date.
+ */
 - (void)setLastUpdatedAt:(NSDate *)date withPullToRefreshView:(SSPullToRefreshView *)view;
 
 @end