Add comment to core libs.

ptr-lib/src/in/srain/cube/views/ptr/PtrClassicDefaultHeader.java

@@ -16,6 +16,9 @@
 import java.text.SimpleDateFormat;
 import java.util.Date;
 
+/**
+ * If header not specified, ptr frame would use this as header view.
+ */
 public class PtrClassicDefaultHeader extends FrameLayout implements PtrUIHandler {
 
     private final static String KEY_SharedPreferences = "cube_ptr_classic_last_update";

ptr-lib/src/in/srain/cube/views/ptr/PtrClassicFrameLayout.java

@@ -3,6 +3,9 @@
 import android.content.Context;
 import android.util.AttributeSet;
 
+/**
+ * PtrFrameLayout which use {@link PtrClassicDefaultHeader} as header view.
+ */
 public class PtrClassicFrameLayout extends PtrFrameLayout {
 
     private PtrClassicDefaultHeader mPtrClassicHeader;

ptr-lib/src/in/srain/cube/views/ptr/PtrDefaultHandler.java

@@ -3,8 +3,18 @@
 import android.view.View;
 import android.widget.AbsListView;
 
+/**
+ * Basic handler wrap the logic of {@link PtrHandler#checkCanDoRefresh(PtrFrameLayout, View, View)}.
+ * This default handler make ptr only response to move down when the content in initial position.
+ */
 public abstract class PtrDefaultHandler implements PtrHandler {
 
+    /**
+     * Judge if contents can move up.
+     *
+     * @param view
+     * @return
+     */
     public static boolean canChildScrollUp(View view) {
         if (android.os.Build.VERSION.SDK_INT < 14) {
             if (view instanceof AbsListView) {

ptr-lib/src/in/srain/cube/views/ptr/PtrFrameLayout.java

@@ -41,6 +41,10 @@ public class PtrFrameLayout extends ViewGroup {
     private int mDurationToCloseHeader = 1000;
     private boolean mKeepHeaderWhenRefresh = true;
     private boolean mPullToRefresh = false;
+
+    /**
+     *  Header view which would be "pull down" when perform pull down to refresh.
+     */
     private View mHeaderView;
     private PtrUIHandlerHolder mPtrUIHandlerHolder = PtrUIHandlerHolder.create();
     private PtrHandler mPtrHandler;
@@ -110,6 +114,14 @@ public PtrFrameLayout(Context context, AttributeSet attrs, int defStyle) {
         mPagingTouchSlop = conf.getScaledTouchSlop() * 2;
     }
 
+    /**
+     * Find it's child layout as header and content. Exception would throw if there are more than
+     * two child layouts.
+     *
+     * If there are two child layouts, it would find out header and content by resource id or class type.
+     * If there only one child layouts, it would be regard as content.
+     * If there is no child layout, a error hint would show.
+     */
     @Override
     protected void onFinishInflate() {
         final int childCount = getChildCount();
@@ -211,6 +223,14 @@ protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {
         }
     }
 
+    /**
+     * Measure content view by ptr frame's layout measure spec. Ptr frame's padding and content margin
+     * would be added and become new padding.
+     *
+     * @param child content
+     * @param parentWidthMeasureSpec ptr frame's width measure spec.
+     * @param parentHeightMeasureSpec ptr frame's height measure spec.
+     */
     private void measureContentView(View child,
                                     int parentWidthMeasureSpec,
                                     int parentHeightMeasureSpec) {
@@ -229,6 +249,9 @@ protected void onLayout(boolean flag, int i, int j, int k, int l) {
         layoutChildren();
     }
 
+    /**
+     * Layout header above the Ptr frame, put content on Ptr frame's position.
+     */
     private void layoutChildren() {
         int offsetX = mPtrIndicator.getCurrentPosY();
         int paddingLeft = getPaddingLeft();
@@ -340,9 +363,9 @@ public boolean dispatchTouchEvent(MotionEvent e) {
     }
 
     /**
-     * if deltaY > 0, move the content down
+     * Update ptr indicator's coordination, and invoke position change.
      *
-     * @param deltaY
+     * @param deltaY positive value would move the content down
      */
     private void movePos(float deltaY) {
         // has reached the top
@@ -368,6 +391,11 @@ private void movePos(float deltaY) {
         updatePos(change);
     }
 
+    /**
+     * Apply position change to the view.
+     *
+     * @param change positive value would move the content down
+     */
     private void updatePos(int change) {
         if (change == 0) {
             return;
@@ -432,8 +460,14 @@ private void updatePos(int change) {
         onPositionChange(isUnderTouch, mStatus, mPtrIndicator);
     }
 
-    protected void onPositionChange(boolean isInTouching, byte status, PtrIndicator mPtrIndicator) {
-    }
+    /**
+     * Called when position change.
+     *
+     * @param isInTouching
+     * @param status
+     * @param mPtrIndicator
+     */
+    protected void onPositionChange(boolean isInTouching, byte status, PtrIndicator mPtrIndicator) {}
 
     @SuppressWarnings("unused")
     public int getHeaderHeight() {
@@ -466,11 +500,10 @@ private void onRelease(boolean stayForLoading) {
     }
 
     /**
-     * please DO REMEMBER resume the hook
+     * please DO REMEMBER resume the hook, or your UI would never receive REFRESH COMPLETE event!
      *
      * @param hook
      */
-
     public void setRefreshCompleteHook(PtrUIHandlerHook hook) {
         mRefreshCompleteHook = hook;
         hook.setResumeAction(new Runnable() {
@@ -886,6 +919,10 @@ public void setHeaderView(View header) {
         }
         mHeaderView = header;
         addView(header);
+
+        if(header instanceof PtrUIHandler){
+            addPtrUIHandler((PtrUIHandler) header);
+        }
     }
 
     @Override
@@ -951,6 +988,10 @@ public LayoutParams(ViewGroup.LayoutParams source) {
         }
     }
 
+    /**
+     * Runnable to track position change of Scroller. It will get the coordinate change
+     * and apply it to the Layout.
+     */
     class ScrollChecker implements Runnable {
 
         private int mLastFlingY;
@@ -1014,6 +1055,12 @@ public void abortIfWorking() {
             }
         }
 
+        /**
+         * If not in target position, let Scroller start scroll to destination.
+         *
+         * @param to target coordination.
+         * @param duration scroll duration.
+         */
         public void tryToScrollTo(int to, int duration) {
             if (mPtrIndicator.isAlreadyHere(to)) {
                 return;

ptr-lib/src/in/srain/cube/views/ptr/PtrHandler.java

@@ -2,6 +2,26 @@
 
 import android.view.View;
 
+/**
+ * Wrap base refresh event, you can use {@link PtrFrameLayout#setPtrHandler(PtrHandler)} to
+ * set your Handler and do refresh in onRefreshBegin().
+ *
+ * <p>Here is a simple example:</p>
+ *
+ * <pre>
+ * ptrFrame.setPtrHandler(new PtrDefaultHandler() {
+ *     @Override
+ *     public void onRefreshBegin(PtrFrameLayout frame) {
+ *         // do refresh.
+ *     }
+ *
+ *     @Override
+ *     public boolean checkCanDoRefresh(PtrFrameLayout frame, View content, View header) {
+ *         return true;
+ *     }
+ * });
+ * </pre>
+ */
 public interface PtrHandler {
 
     /**
@@ -12,7 +32,7 @@ public interface PtrHandler {
     public boolean checkCanDoRefresh(final PtrFrameLayout frame, final View content, final View header);
 
     /**
-     * When refresh begin
+     * Called when refresh begin.
      *
      * @param frame
      */

ptr-lib/src/in/srain/cube/views/ptr/PtrUIHandler.java

@@ -3,33 +3,53 @@
 import in.srain.cube.views.ptr.indicator.PtrIndicator;
 
 /**
- *
+ * Wrap base UI event. Your header view should implement this class if you want it response to
+ * Ptr events.
  */
 public interface PtrUIHandler {
 
     /**
-     * When the content view has reached top and refresh has been completed, view will be reset.
+     * Called when the Ptr has back to initial position and refresh has been completed,
+     * then view will be reset.
      *
-     * @param frame
+     * @param frame ptr frame layout.
      */
     public void onUIReset(PtrFrameLayout frame);
 
     /**
-     * prepare for loading
+     * Called when the Ptr leave initial position or just refresh complete.
      *
-     * @param frame
+     * @param frame ptr frame layout.
      */
     public void onUIRefreshPrepare(PtrFrameLayout frame);
 
     /**
-     * perform refreshing UI
+     * Called when the Ptr begin to perform refresh.
+     *
+     * @param frame ptr frame layout.
      */
     public void onUIRefreshBegin(PtrFrameLayout frame);
 
     /**
-     * perform UI after refresh
+     * Called when the Ptr refresh finished.
+     *
+     * @param frame ptr frame layout.
      */
     public void onUIRefreshComplete(PtrFrameLayout frame);
 
+    /**
+     * Called when the Ptr position updated.
+     *
+     * @param frame ptr frame layout.
+     * @param isUnderTouch true if is moved under touch.
+     * @param status ptr status, it should be one of the following value:
+     * <ul>
+     *   <li>{@link PtrFrameLayout#PTR_STATUS_INIT}</li>
+     *   <li>{@link PtrFrameLayout#PTR_STATUS_PREPARE}</li>
+     *   <li>{@link PtrFrameLayout#PTR_STATUS_LOADING}</li>
+     *   <li>{@link PtrFrameLayout#PTR_STATUS_COMPLETE}</li>
+     * </ul>
+     * @param ptrIndicator ptr indicator.
+     */
     public void onUIPositionChange(PtrFrameLayout frame, boolean isUnderTouch, byte status, PtrIndicator ptrIndicator);
 }

ptr-lib/src/in/srain/cube/views/ptr/PtrUIHandlerHook.java

@@ -1,9 +1,12 @@
 package in.srain.cube.views.ptr;
 
 /**
- * Run a hook runnable, the runnable will run only once.
- * After the runnable is done, call resume to resume.
- * Once run, call takeover will directory call the resume action
+ * Run a hook runnable, the runnable will run only once after refresh complete.
+ * <p/>
+ * After the runnable is done, you should call resume() to resume!(or your UI would never
+ * reset after refreshed.)
+ * <p/>
+ * Once run, call takeover() will directory call the resume() action
  */
 public abstract class PtrUIHandlerHook implements Runnable {
 

ptr-lib/src/in/srain/cube/views/ptr/indicator/PtrIndicator.java

@@ -2,6 +2,9 @@
 
 import android.graphics.PointF;
 
+/**
+ * Keep states and properties of PullToRefresh.
+ */
 public class PtrIndicator {
 
     public final static int POS_START = 0;
@@ -110,9 +113,7 @@ public final void setCurrentPos(int current) {
         onUpdatePos(current, mLastPos);
     }
 
-    protected void onUpdatePos(int current, int last) {
-
-    }
+    protected void onUpdatePos(int current, int last) {}
 
     public int getHeaderHeight() {
         return mHeaderHeight;