Add annotations

Signed-off-by: Fung <fython@163.com>

library/src/main/java/moe/feng/common/view/breadcrumbs/BreadcrumbsCallback.java

@@ -1,8 +1,25 @@
 package moe.feng.common.view.breadcrumbs;
 
+/**
+ * Interface definition for a callback to be invoked when BreadcrumbsView's item was clicked or changed.
+ */
 public interface BreadcrumbsCallback {
 
+	/**
+	 * Called when BreadcrumbsView's item has been clicked
+	 *
+	 * @param view Parent view
+	 * @param position The position of clicked item
+	 */
 	void onItemClick(BreadcrumbsView view, int position);
+
+	/**
+	 * Called when BreadcrumbsView's item has been changed
+	 *
+	 * @param view Parent view
+	 * @param parentPosition The position of the parent item of changed item
+	 * @param nextItem Next item title
+	 */
 	void onItemChange(BreadcrumbsView view, int parentPosition, String nextItem);
 
 }

library/src/main/java/moe/feng/common/view/breadcrumbs/BreadcrumbsView.java

@@ -18,9 +18,15 @@
 
 public class BreadcrumbsView extends FrameLayout {
 
+	/**
+	 * Internal implement of BreadcrumbsView
+	 */
 	private RecyclerView mRecyclerView;
 	private BreadcrumbsAdapter mAdapter;
 
+	/**
+	 * Popup Menu Theme Id
+	 */
 	private int mPopupThemeId = -1;
 
 	public BreadcrumbsView(Context context) {
@@ -43,19 +49,26 @@ public BreadcrumbsView(Context context, AttributeSet attrs, int defStyleAttr) {
 		init();
 	}
 
+	/**
+	 * Init BreadcrumbsView
+	 */
 	private void init() {
+		// Init RecyclerView
 		if (mRecyclerView == null) {
 			ViewGroup.LayoutParams rvLayoutParams = new ViewGroup.LayoutParams(-1, -1);
 			rvLayoutParams.width = ViewGroup.LayoutParams.MATCH_PARENT;
 			mRecyclerView = new RecyclerView(getContext());
 
+			// Create Horizontal LinearLayoutManager
 			LinearLayoutManager layoutManager = new LinearLayoutManager(
 					getContext(), LinearLayoutManager.HORIZONTAL, ViewUtils.isRtlLayout(getContext()));
 			mRecyclerView.setLayoutManager(layoutManager);
 			mRecyclerView.setOverScrollMode(OVER_SCROLL_NEVER);
 
+			// Add RecyclerView
 			addView(mRecyclerView, rvLayoutParams);
 		}
+		// Init Adapter
 		if (mAdapter == null) {
 			mAdapter = new BreadcrumbsAdapter(this);
 			if (mPopupThemeId != -1) {
@@ -65,14 +78,29 @@ private void init() {
 		mRecyclerView.setAdapter(mAdapter);
 	}
 
+	/**
+	 * Get breadcrumb items list
+	 *
+	 * @return Breadcrumb Items
+	 */
 	public @Nullable ArrayList<BreadcrumbItem> getItems() {
 		return mAdapter.getItems();
 	}
 
+	/**
+	 * Get current breadcrumb item
+	 *
+	 * @return Current item
+	 */
 	public BreadcrumbItem getCurrentItem() {
 		return mAdapter.getItems().get(mAdapter.getItems().size() - 1);
 	}
 
+	/**
+	 * Set breadcrumb items list
+	 *
+	 * @param items Target list
+	 */
 	public void setItems(@Nullable ArrayList<BreadcrumbItem> items) {
 		mAdapter.setItems(items);
 		mAdapter.notifyDataSetChanged();
@@ -84,10 +112,20 @@ public void run() {
 		}, 500);
 	}
 
+	/**
+	 * Notify which item has been changed to update text view
+	 *
+	 * @param index The item position
+	 */
 	public void notifyItemChanged(int index) {
 		mAdapter.notifyItemChanged(index * 2);
 	}
 
+	/**
+	 * Add a new item
+	 *
+	 * @param item New item
+	 */
 	public void addItem(@NonNull BreadcrumbItem item) {
 		int oldSize = mAdapter.getItemCount();
 		mAdapter.getItems().add(item);
@@ -101,6 +139,11 @@ public void run() {
 		}, 500);
 	}
 
+	/**
+	 * Remove items after a position
+	 *
+	 * @param afterPos The first position of the removing range
+	 */
 	public void removeItemAfter(final int afterPos) {
 		if (afterPos <= mAdapter.getItems().size() - 1) {
 			int oldSize = mAdapter.getItemCount();
@@ -120,18 +163,35 @@ public void run() {
 		}
 	}
 
+	/**
+	 * Remove last item
+	 */
 	public void removeLastItem() {
 		removeItemAfter(mAdapter.getItems().size() - 1);
 	}
 
+	/**
+	 * Set BreadcrumbsView callback (Recommend to use DefaultBreadcrumbsCallback)
+	 *
+	 * @param callback Callback should be set
+	 * @see BreadcrumbsCallback
+	 * @see DefaultBreadcrumbsCallback
+	 */
 	public void setCallback(BreadcrumbsCallback callback) {
 		mAdapter.setCallback(callback);
 	}
 
+	/**
+	 * Get callback
+	 *
+	 * @return Callback
+	 * @see BreadcrumbsCallback
+	 */
 	public BreadcrumbsCallback getCallback() {
 		return mAdapter.getCallback();
 	}
 
+	// Save/Restore View Instance State
 	@Override
 	public Parcelable onSaveInstanceState() {
 		Bundle bundle = new Bundle();

library/src/main/java/moe/feng/common/view/breadcrumbs/DefaultBreadcrumbsCallback.java

@@ -2,6 +2,12 @@
 
 import moe.feng.common.view.breadcrumbs.model.BreadcrumbItem;
 
+/**
+ * Simple callback to be invoked when BreadcrumbsView's item was clicked or changed.
+ * Assist you to handle navigate actions.
+ *
+ * @see moe.feng.common.view.breadcrumbs.BreadcrumbsCallback
+ */
 public abstract class DefaultBreadcrumbsCallback implements BreadcrumbsCallback {
 
 	@Override
@@ -22,7 +28,20 @@ public void onItemChange(BreadcrumbsView view, int parentPosition, String nextIt
 		this.onNavigateNewLocation(nextBreadcrumb, parentPosition + 1);
 	}
 
+	/**
+	 * Called when page should navigate back to a location.
+	 *
+	 * @param item The item that was navigated to
+	 * @param position The position of new location
+	 */
 	public abstract void onNavigateBack(BreadcrumbItem item, int position);
+
+	/**
+	 * Called when page should navigate to the location where was changed by popup menu
+	 *
+	 * @param newItem The item that was navigated to
+	 * @param changedPosition The position of changed location
+	 */
 	public abstract void onNavigateNewLocation(BreadcrumbItem newItem, int changedPosition);
 
 }

library/src/main/java/moe/feng/common/view/breadcrumbs/ViewUtils.java

@@ -4,24 +4,45 @@
 import android.content.res.TypedArray;
 import android.graphics.Color;
 import android.support.annotation.AttrRes;
+import android.support.annotation.ColorInt;
 import android.view.View;
 import android.view.ViewGroup;
 import android.widget.FrameLayout;
 import android.widget.ListAdapter;
 
 class ViewUtils {
 
+	/**
+	 * Check if the current language is RTL
+	 *
+	 * @param context Context
+	 * @return Result
+	 */
 	static boolean isRtlLayout(Context context) {
 		return context.getResources().getConfiguration().getLayoutDirection() == View.LAYOUT_DIRECTION_RTL;
 	}
 
-	static int getColorFromAttr(Context context, @AttrRes int attr) {
+	/**
+	 * Get color attribute from current theme
+	 *
+	 * @param context Themed context
+	 * @param attr The resource id of color attribute
+	 * @return Result
+	 */
+	@ColorInt static int getColorFromAttr(Context context, @AttrRes int attr) {
 		TypedArray array = context.getTheme().obtainStyledAttributes(new int[]{attr});
 		int color = array.getColor(0, Color.TRANSPARENT);
 		array.recycle();
 		return color;
 	}
 
+	/**
+	 * Measure content width from ListAdapter
+	 *
+	 * @param context Context
+	 * @param listAdapter The adapter that should be measured
+	 * @return Recommend popup window width
+	 */
 	static int measureContentWidth(Context context, ListAdapter listAdapter) {
 		ViewGroup mMeasureParent = null;
 		int maxWidth = 0;