Updated Documentation

Author: brianwernick

library/src/main/java/com/devbrackets/android/recyclerext/decoration/SpacerDecoration.java

@@ -60,6 +60,13 @@ public void update(int horizontalSpace, int verticalSpace) {
         this.verticalSpace = verticalSpace;
     }
 
+    /**
+     * Sets the edges that are allowed to add spacing.  Edges are
+     * the left side of the left-most items, the right side of the right-most items,
+     * the top side of the top-most items, and the bottom side of the bottom-most items.
+     *
+     * @param edgeSpacingFlags The flags for which edges to add padding to
+     */
     public void setAllowedEdgeSpacing(@EdgeSpacing int edgeSpacingFlags) {
         allowedEdgeSpacing = edgeSpacingFlags;
     }
@@ -79,6 +86,14 @@ public void getItemOffsets(Rect outRect, View view, RecyclerView parent, Recycle
         outRect.bottom = (allowedEdgeSpacing & EDGE_SPACING_BOTTOM) == 0 && isBottomEdge(spanLookup, position, childCount) ? 0 : verticalSpace;
     }
 
+    /**
+     * Determines if the item at <code>position</code> is a top-most view
+     *
+     * @param spanLookup The SpanLookup related to the parent RecyclerView
+     * @param position The position to determine if the view is a top-most view
+     * @param childCount The number of children in the RecyclerView (adapter)
+     * @return True if the view at <code>position</code> is a top-most view
+     */
     protected boolean isTopEdge(SpanLookup spanLookup, int position, int childCount) {
         int latestCheckedPosition = 0;
         for (; latestCheckedPosition < childCount; latestCheckedPosition++) {
@@ -91,11 +106,26 @@ protected boolean isTopEdge(SpanLookup spanLookup, int position, int childCount)
         return position <= latestCheckedPosition;
     }
 
+    /**
+     * Determines if the item at <code>position</code> is a right-most view
+     *
+     * @param spanLookup The SpanLookup related to the parent RecyclerView
+     * @param position The position to determine if the view is a right-most view
+     * @return True if the view at <code>position</code> is a right-most view
+     */
     protected boolean isRightEdge(SpanLookup spanLookup, int position) {
         int spanIndex = spanLookup.getIndex(position);
         return (spanIndex + spanLookup.getSpanSize(position)) == spanLookup.getSpanCount();
     }
 
+    /**
+     * Determines if the item at <code>position</code> is a bottom-most view
+     *
+     * @param spanLookup The SpanLookup related to the parent RecyclerView
+     * @param position The position to determine if the view is a bottom-most view
+     * @param childCount The number of children in the RecyclerView (adapter)
+     * @return True if the view at <code>position</code> is a bottom-most view
+     */
     protected boolean isBottomEdge(SpanLookup spanLookup, int position, int childCount) {
         int latestCheckedPosition = childCount -1;
         for (; latestCheckedPosition >= 0; latestCheckedPosition--) {
@@ -108,11 +138,21 @@ protected boolean isBottomEdge(SpanLookup spanLookup, int position, int childCou
         return position >= latestCheckedPosition;
     }
 
+    /**
+     * Determines if the item at <code>position</code> is a left-most view
+     *
+     * @param spanLookup The SpanLookup related to the parent RecyclerView
+     * @param position The position to determine if the view is a left-most view
+     * @return True if the view at <code>position</code> is a left-most view
+     */
     protected boolean isLeftEdge(SpanLookup spanLookup, int position) {
         int spanIndex = spanLookup.getIndex(position);
         return spanIndex == 0;
     }
 
+    /**
+     * A helper class to abstract the lookup from different LayoutManagers
+     */
     protected class SpanLookup {
         public WeakReference<GridLayoutManager> gridLayoutManager = new WeakReference<>(null);
 

library/src/main/java/com/devbrackets/android/recyclerext/layoutmanager/AutoColumnGridLayoutManager.java

@@ -219,6 +219,15 @@ protected int determineColumnCount(int gridItemWidth) {
         return columnCount;
     }
 
+    /**
+     * Calculates and adds the amount of spacing that needs to be between each
+     * column, row, and the edges of the RecyclerView.  This pays attention to
+     * the value from {@link #setSpacingMethod(SpacingMethod)}
+     *
+     * @param recyclerView The RecyclerView to use for determining the amount of space that needs to be added
+     * @param gridItemWidth The requested width for the items
+     * @param columnCount The number of columns to display
+     */
     protected void updateSpacing(RecyclerView recyclerView, int gridItemWidth, int columnCount) {
         //Sets the decoration for the calculated spacing
         if (spacerDecoration == null) {
@@ -241,12 +250,9 @@ protected void updateSpacing(RecyclerView recyclerView, int gridItemWidth, int c
         int freeSpace = usableWidth - (gridItemWidth * columnCount);
         int extraSpace = freeSpace - (2 * minColumnSpacingEdge) - (separatorCount * minColumnSpacingSeparator);
 
+        //If we can add spacing, then we need to calculate how much and where to add it
         if (extraSpace >= spacerCount) {
-            if (spacingMethod == SpacingMethod.EDGES) {
-                edgeSpacing = (freeSpace - (separatorSpacing * spacerCount)) / 2;
-            } else if (spacingMethod == SpacingMethod.SEPARATOR) {
-                separatorSpacing = spacerCount == 0 ? 0 : freeSpace / spacerCount;
-            } else {
+            if (spacingMethod == SpacingMethod.ALL) {
                 int totalMinEdges = minColumnSpacingEdge * 2;
                 int totalMinSeparators = separatorCount * minColumnSpacingSeparator;
 
@@ -257,6 +263,10 @@ protected void updateSpacing(RecyclerView recyclerView, int gridItemWidth, int c
 
                 separatorSpacing = spacerCount == 0 ? 0 : totalSeparatorSpace / spacerCount;
                 edgeSpacing = ((freeSpace - totalSeparatorSpace) / 2) + separatorSpacing;
+            } else if (spacingMethod == SpacingMethod.EDGES) {
+                edgeSpacing = (freeSpace - (separatorSpacing * spacerCount)) / 2;
+            } else { //SEPARATOR
+                separatorSpacing = spacerCount == 0 ? 0 : freeSpace / spacerCount;
             }
 
             edgeSpacing -= separatorSpacing;
@@ -274,6 +284,16 @@ protected void updateSpacing(RecyclerView recyclerView, int gridItemWidth, int c
         spacerDecoration.update(separatorSpacing, matchSpacing ? separatorSpacing : rowSpacing / 2);
     }
 
+    /**
+     * Performs the actual calculation for determining the number of possible
+     * columns by using the {@link #maxColumnCount}, {@link #minColumnSpacingEdge}, and
+     * {@link #minColumnSpacingSeparator} in conjunction with the requested width
+     * for the items
+     *
+     * @param recyclerView The RecyclerView to use when determining the possible number of columns
+     * @param gridItemWidth The requested width for items to be
+     * @return The calculated number of possible columns
+     */
     protected int getColumnCount(RecyclerView recyclerView, int gridItemWidth) {
         int padding = recyclerView.getPaddingLeft() + recyclerView.getPaddingRight();
         int usableWidth = recyclerView.getWidth() - padding;
@@ -297,6 +317,13 @@ protected int getColumnCount(RecyclerView recyclerView, int gridItemWidth) {
         return columnCount;
     }
 
+    /**
+     * Removes the padding previously added to the <code>recyclerView</code>
+     * for the edge spacing.  If no padding was previously added, then this
+     * has no affect
+     *
+     * @param recyclerView The RecyclerView to remove the padding from
+     */
     protected void resetRecyclerPadding(RecyclerView recyclerView) {
         recyclerView.setPadding(
                 recyclerView.getPaddingLeft() - edgeSpacing,