Document the public API in the Javadoc

README.md

@@ -20,7 +20,7 @@ The library is published on Maven Central, add the dependency (remember to check
 
 ```groovy
     dependencies {
-        implementation 'io.github.simonebortolin:FlowLayoutManager:1.10.1'
+        implementation 'io.github.simonebortolin:FlowLayoutManager:1.10.2'
     }
 ```
 

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/Alignment.java

@@ -1,10 +1,16 @@
 package com.xiaofeng.flowlayoutmanager;
 
 /**
- * Created by xhan on 4/11/16.
+ * Horizontal alignment of the items in each line of a {@link FlowLayoutManager}.
+ *
+ * @author xhan
+ * @see FlowLayoutManager#setAlignment(Alignment)
  */
 public enum Alignment {
-	LEFT,
+    /** Items start from the left edge, lines are filled left to right. */
+    LEFT,
+    /** Items start from the right edge, lines are filled right to left. */
     RIGHT,
+    /** Items are laid out left to right and each line is centered. */
     CENTER
 }

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutManager.java

@@ -17,8 +17,19 @@
 import java.util.List;
 
 /**
- * Layout manager for flow views. support different view height, support item add/removed notification
- * support align to left/right edge. support scroll/smooth scroll.
+ * A {@link RecyclerView.LayoutManager} that lays out items in flow style: items are placed in a
+ * line until it is full, then a new line starts, like words in a paragraph.
+ *
+ * <p>Items can have different sizes. It supports predictive item animations, scroll and smooth
+ * scroll, auto measurement, left, right or center alignment ({@link #setAlignment(Alignment)}),
+ * a limit of items per line ({@link #maxItemsPerLine(int)}, {@link #singleItemPerLine()}) and a
+ * limit of lines ({@link #maxLines(int)}).
+ *
+ * <pre>{@code
+ * recyclerView.setLayoutManager(new FlowLayoutManager()
+ *         .setAlignment(Alignment.LEFT)
+ *         .maxItemsPerLine(3));
+ * }</pre>
  */
 public class FlowLayoutManager extends RecyclerView.LayoutManager {
 
@@ -38,11 +49,16 @@ public class FlowLayoutManager extends RecyclerView.LayoutManager {
     // number of items that fit in the first maxLines lines, refreshed on every real layout.
     private int maxLinesItemCount = Integer.MAX_VALUE;
 
+    /**
+     * Creates a layout manager with centered lines and no limits.
+     */
     public FlowLayoutManager() {
         flowLayoutOptions = new FlowLayoutOptions();
     }
 
     /**
+     * Creates a layout manager with centered lines that shows at most {@code maxLines} lines.
+     *
      * @param maxLines max number of lines to show, &lt;= 0 to show all lines.
      */
     public FlowLayoutManager(int maxLines) {
@@ -671,6 +687,10 @@ private int getChildAdapterPosition(View child) {
         return ((RecyclerView.LayoutParams) child.getLayoutParams()).getViewAdapterPosition();
     }
 
+    /**
+     * @param child a child view of the RecyclerView
+     * @return the layout position of {@code child}
+     */
     public int getChildLayoutPosition(View child) {
         return ((RecyclerView.LayoutParams) child.getLayoutParams()).getViewLayoutPosition();
     }
@@ -766,11 +786,22 @@ private boolean isChildRemoved(View child) {
         return ((RecyclerView.LayoutParams) child.getLayoutParams()).isItemRemoved();
     }
 
+    /**
+     * Sets the alignment of the items in each line, {@link Alignment#CENTER} by default.
+     *
+     * @param alignment the alignment
+     * @return this layout manager
+     */
     public FlowLayoutManager setAlignment(Alignment alignment) {
         flowLayoutOptions.alignment = alignment;
         return this;
     }
 
+    /**
+     * Puts each item in its own line, same as {@code maxItemsPerLine(1)}.
+     *
+     * @return this layout manager
+     */
     public FlowLayoutManager singleItemPerLine() {
         flowLayoutOptions.itemsPerLine = 1;
 
@@ -783,6 +814,12 @@ public FlowLayoutManager singleItemPerLine() {
         return this;
     }
 
+    /**
+     * Puts at most {@code itemsPerLine} items in each line.
+     *
+     * @param itemsPerLine max number of items in a line, &lt;= 0 for no limit
+     * @return this layout manager
+     */
     public FlowLayoutManager maxItemsPerLine(int itemsPerLine) {
         flowLayoutOptions.itemsPerLine = itemsPerLine;
 
@@ -796,14 +833,22 @@ public FlowLayoutManager maxItemsPerLine(int itemsPerLine) {
     }
 
     /**
-     * Show at most maxLines lines, items after the last line are not laid out.
+     * Shows at most {@code maxLines} lines, items after the last line are not laid out.
+     *
+     * @param maxLines max number of lines to show, &lt;= 0 to show all lines
+     * @return this layout manager
      */
     public FlowLayoutManager maxLines(int maxLines) {
         flowLayoutOptions.maxLines = maxLines;
         requestLayout();
         return this;
     }
 
+    /**
+     * Shows all lines, removing the limit set with {@link #maxLines(int)}.
+     *
+     * @return this layout manager
+     */
     public FlowLayoutManager removeMaxLinesLimit() {
         return maxLines(FlowLayoutOptions.MAX_LINES_NO_LIMIT);
     }
@@ -856,6 +901,12 @@ private int countItemsInMaxLines(RecyclerView.Recycler recycler) {
         return itemCount;
     }
 
+    /**
+     * Puts as many items in a line as fit, removing the limit set with
+     * {@link #maxItemsPerLine(int)} or {@link #singleItemPerLine()}.
+     *
+     * @return this layout manager
+     */
     public FlowLayoutManager removeItemPerLineLimit() {
         flowLayoutOptions.itemsPerLine = FlowLayoutOptions.ITEM_PER_LINE_NO_LIMIT;
 

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/FlowLayoutOptions.java

@@ -1,19 +1,33 @@
 package com.xiaofeng.flowlayoutmanager;
 
 /**
- * Created by xhan on 4/11/16.
+ * Layout options of a {@link FlowLayoutManager}: alignment, items per line and max lines.
+ * Set them with the {@link FlowLayoutManager} builder methods.
+ *
+ * @author xhan
  */
 public class FlowLayoutOptions {
+    /** Value of {@link #itemsPerLine} that puts as many items in a line as fit. */
 	public static final int ITEM_PER_LINE_NO_LIMIT = 0;
+    /** Value of {@link #maxLines} that shows all lines. */
 	public static final int MAX_LINES_NO_LIMIT = 0;
+    /** Alignment of the items in each line, {@link Alignment#CENTER} by default. */
     public Alignment alignment = Alignment.CENTER;
+    /**
+     * Max number of items in a line. {@link #ITEM_PER_LINE_NO_LIMIT} (or any value <= 0)
+     * puts as many items as fit.
+     */
     public int itemsPerLine = ITEM_PER_LINE_NO_LIMIT;
     /**
      * Max number of lines to show, items after the last line are not laid out.
      * {@link #MAX_LINES_NO_LIMIT} (or any value <= 0) shows all lines.
      */
     public int maxLines = MAX_LINES_NO_LIMIT;
 
+    /**
+     * @param layoutOptions options to copy
+     * @return a copy of {@code layoutOptions}
+     */
 	public static FlowLayoutOptions clone(FlowLayoutOptions layoutOptions) {
 		FlowLayoutOptions result = new FlowLayoutOptions();
 		result.alignment = layoutOptions.alignment;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutContext.java

@@ -1,7 +1,10 @@
 package com.xiaofeng.flowlayoutmanager;
 
 /**
- * Created by xhan on 4/11/16.
+ * State of a layout pass: the layout options and the number of items already placed in the
+ * current line. Used internally by {@link FlowLayoutManager}.
+ *
+ * @author xhan
  */
 public class LayoutContext {
 	public FlowLayoutOptions layoutOptions;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutHelper.java

@@ -4,7 +4,10 @@
 import androidx.recyclerview.widget.RecyclerView;
 
 /**
- * Created by xhan on 4/11/16.
+ * Geometry helpers of the visible area and of the line breaking rules. Used internally by
+ * {@link FlowLayoutManager}.
+ *
+ * @author xhan
  */
 public class LayoutHelper {
 	RecyclerView.LayoutManager layoutManager;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/LayoutManagerAppender.java

@@ -5,9 +5,11 @@
 import android.view.View;
 
 /**
- * Created by Anton Dudakov (dude.bw@gmail.com) on 04/10/16.
+ * A view measured in a line, laid out once the line is complete so that it can be shifted
+ * for {@link Alignment#CENTER}. Used internally by {@link FlowLayoutManager}.
+ *
+ * @author Anton Dudakov
  */
-
 public class LayoutManagerAppender {
 
     View mView;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/ScrollbarHelper.java

@@ -16,16 +16,14 @@
 
 package com.xiaofeng.flowlayoutmanager;
 
-/**
- * Created by Anton Dudakov (dude.bw@gmail.com) on 13/10/16.
- */
-
 import androidx.recyclerview.widget.OrientationHelper;
 import androidx.recyclerview.widget.RecyclerView;
 import android.view.View;
 
 /**
  * A helper class to do scroll offset calculations.
+ *
+ * @author Anton Dudakov
  */
 class ScrollbarHelper {
 

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/CacheHelper.java

@@ -4,8 +4,9 @@
 import android.util.SparseArray;
 
 /**
- * A Helper class that will save Line information (items count, total width etc.) and will be used
- * for layout, that will avoid low efficiency layout
+ * Cache of the item sizes and of the resulting lines (item count, total width etc.), so that
+ * {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager} does not have to lay out every item
+ * from the beginning when scrolling. Used internally by the layout manager.
  */
 public class CacheHelper {
 	public static final int NOT_FOUND = -1;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/Line.java

@@ -1,7 +1,9 @@
 package com.xiaofeng.flowlayoutmanager.cache;
 
 /**
- * Created by xhan on 4/28/16.
+ * Cached information of a laid out line: item count, total width and tallest item.
+ *
+ * @author xhan
  */
 public class Line {
 	public int itemCount;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/cache/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Line cache used internally by {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager}.
+ */
+package com.xiaofeng.flowlayoutmanager.cache;

flowlayoutmanager/src/main/java/com/xiaofeng/flowlayoutmanager/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager}, a RecyclerView layout manager that lays
+ * out items in flow style, and its options.
+ *
+ * <p>Use {@link com.xiaofeng.flowlayoutmanager.FlowLayoutManager} and
+ * {@link com.xiaofeng.flowlayoutmanager.Alignment}; the other classes are used internally by the
+ * layout manager.
+ */
+package com.xiaofeng.flowlayoutmanager;

gradle.properties

@@ -1,6 +1,6 @@
 # Version of the library and of the sample app, used by CI to tag and release.
-VERSION_NAME=1.10.1
-VERSION_CODE=21
+VERSION_NAME=1.10.2
+VERSION_CODE=22
 # Keep it as low as the dependencies allow, library and sample app share it.
 MIN_SDK=21