From 2d1887b783eb44f9ce1566e7a4fec22736b87064 Mon Sep 17 00:00:00 2001 From: ThisIsNsh Date: Tue, 6 Aug 2019 01:17:21 +0530 Subject: [PATCH] Added Javadoc style guide --- .../com/thisisnsh/sugarlibrary/CandyView.java | 145 ++++++++++++++++-- .../thisisnsh/sugarlibrary/CreamAdapter.java | 103 ++++++++++++- 2 files changed, 232 insertions(+), 16 deletions(-) diff --git a/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CandyView.java b/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CandyView.java index e88b8ee..5954f0c 100644 --- a/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CandyView.java +++ b/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CandyView.java @@ -16,9 +16,60 @@ public class CandyView extends RecyclerView implements CreamAdapter.CreamAdapterListener { + /** + * CreamAdapter stores the adapter instance which is + * initialized in the CandyView constructor. + */ CreamAdapter creamAdapter; + + /** + * SugarListener provides additional functionalities + * like to find if the views are created. + */ SugarListener listener; + /** + * Simple constructor to initialize CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + */ + public CandyView(@NonNull Context context) { + super(context); + this.listener = null; + } + + /** + * Simple constructor to initialize CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + */ + public CandyView(@NonNull Context context, @Nullable AttributeSet attrs) { + super(context, attrs); + this.listener = null; + } + + /** + * Simple constructor to initialize CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + */ + public CandyView(@NonNull Context context, @Nullable AttributeSet attrs, int defStyle) { + super(context, attrs, defStyle); + this.listener = null; + } + + /** + * Simple method to make and use CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param adapterLayout Integer to store adapter layout ID. + * @param data Every time this is similar to something. + * @param model This is the class of your data model. + */ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull List data, @NonNull Class model) { creamAdapter = new CreamAdapter(context, adapterLayout, getDataMap(data, model)); creamAdapter.setCreamAdapterListener(this); @@ -26,6 +77,17 @@ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull setLayoutManager(new LinearLayoutManager(context)); } + /** + * Simple method to make and use CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param adapterLayout Integer to store adapter layout ID. + * @param data Every time this is similar to something. + * @param model This is the class of your data model. + * @param layoutManager The LayoutManager specifies the orientation for the + * arrangement of the views in the CandyView. + */ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull List data, @NonNull Class model, @NonNull LayoutManager layoutManager) { this.creamAdapter = new CreamAdapter(context, adapterLayout, getDataMap(data, model)); this.creamAdapter.setCreamAdapterListener(this); @@ -33,6 +95,17 @@ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull this.setLayoutManager(layoutManager); } + /** + * Simple method to make and use CandyView. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param adapterLayout Integer to store adapter layout ID. + * @param data Every time this is similar to something. + * @param model This is the class of your data model. + * @param isHorizontal The LayoutManager specified is LinearLayoutManager + * the orientation is horizontal if the param is true. + */ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull List data, @NonNull Class model, @NonNull boolean isHorizontal) { this.creamAdapter = new CreamAdapter(context, adapterLayout, getDataMap(data, model)); this.creamAdapter.setCreamAdapterListener(this); @@ -43,44 +116,83 @@ public void make(@NonNull Context context, @NonNull int adapterLayout, @NonNull this.setLayoutManager(new LinearLayoutManager(context, LinearLayoutManager.HORIZONTAL, false)); } - public CandyView(@NonNull Context context) { - super(context); - this.listener = null; - } - - public CandyView(@NonNull Context context, @Nullable AttributeSet attrs) { - super(context, attrs); - this.listener = null; - } - - public CandyView(@NonNull Context context, @Nullable AttributeSet attrs, int defStyle) { - super(context, attrs, defStyle); - this.listener = null; - } - + /** + * Method to set SugarListener on CandyView object. + * + * @param listener The Listener is set to the member variable listener + * which was earlier set to null. + */ public void addSugarListener(SugarListener listener) { this.listener = listener; } + /** + * Method provides current position of the recycled view + * & child views in that adapter view. + * + * @param view The View gives all the views recycled for + * a position. + * @param position The int gives the current position of + * the recycled view. + */ @Override public void onNewPosition(View view, int position) { listener.onCandyRecycled(view, position); } + /** + * Method which is called as soon as the layout is + * inflated and child views are added to viewList. + */ @Override public void onFinishInit() { listener.onCandyMade(); } + /** + * Method returns the View of the requested ID. + * + * @param id The int is the ID of some view + * whose View is to be used for some logic. + */ public View getViewById(@NonNull final int id) { return creamAdapter.getViewById(id); } + /** + * Simple interface for SugarListener. + */ public interface SugarListener { + + /** + * Method provides current position of the candy view + * & child views in that adapter view. + * + * @param view The View gives all the views recycled for + * a position. + * @param position The int gives the current position of + * the candy view. + */ void onCandyRecycled(View view, int position); + + /** + * Method which is called as soon as the layout is + * inflated and child views are added to viewList. + */ void onCandyMade(); } + /** + * Method which takes in data in List of Model form but get result + * in List of Map form. The views when added to viewList is circulated in on group. + * + * The model class is searched for all the fields and the name and type bhi done. + * + * @param data The List of ? is very romantic. The data list is iterated for all + * fields in the model class and put them in a list of maps. + * + * @param model The Class specifies the class of List Model. + */ public List> getDataMap(List data, Class model) { List> dataMap = new ArrayList<>(); try { @@ -100,6 +212,9 @@ public List> getDataMap(List data, Class model) { return dataMap; } + /** + * Method creates new Maps as they are call by reference so more than relation can be a problem. + */ public Map getMap() { return new HashMap<>(); } diff --git a/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CreamAdapter.java b/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CreamAdapter.java index c1aff21..c7861ac 100644 --- a/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CreamAdapter.java +++ b/SugarLibrary/src/main/java/com/thisisnsh/sugarlibrary/CreamAdapter.java @@ -18,12 +18,45 @@ public class CreamAdapter extends RecyclerView.Adapter { + /** + * Integer to store adapter layout ID. + */ private int adapterLayout; + + /** + * Context object to store the context of calling Activity. + */ private Context context; + + /** + * List of View which takes in all the child views of inflated adapterLayout. + */ private List viewList; + + /** + * List of Map stores the data map which is sent by the CandyView. + * + * @see com.thisisnsh.sugarlibrary.CandyView#getDataMap(List, Class) + */ private List> dataMap; + + /** + * Listener object which provides two methods + * onNewPosition() & onFinishInit() + * + * @see CreamAdapter.CreamAdapterListener#onNewPosition(View, int) + * @see CreamAdapterListener#onFinishInit() + */ private CreamAdapterListener listener; + /** + * Constructor to use when creating an adapter. + * + * @param context The Context the view is running in, through which it can + * access the current theme, resources, etc. + * @param adapterLayout The ID of the layout for the adapter. + * @param context The List of Maps which contains the data stored as List of Model in calling Activity. + */ public CreamAdapter(Context context, int adapterLayout, List> dataMap) { this.adapterLayout = adapterLayout; this.context = context; @@ -31,6 +64,13 @@ public CreamAdapter(Context context, int adapterLayout, List this.listener = null; } + /** + * Override method of RecyclerView.Adapter class. + * The layout to be inflated is passed in the LayoutInflator and the view is + * returned as SuperViewHolder class instance. + * + * @see CreamAdapter.SuperViewHolder + */ @NonNull @Override public SuperViewHolder onCreateViewHolder(@NonNull ViewGroup viewGroup, int i) { @@ -38,6 +78,16 @@ public SuperViewHolder onCreateViewHolder(@NonNull ViewGroup viewGroup, int i) { return new SuperViewHolder(view); } + /** + * Override method of RecyclerView.Adapter class. + * + * Whenever the views are recycled or are about to + * recycle this method is called. The viewList is iterated + * and the data present at the position i is put in the views. + * + * Map contains the view id and data. So the iteration puts the + * data in the correct views by checking their IDs. + */ @Override public void onBindViewHolder(@NonNull SuperViewHolder superViewHolder, int i) { for (int counter = 0; counter < viewList.size(); counter++) { @@ -62,11 +112,19 @@ public void onBindViewHolder(@NonNull SuperViewHolder superViewHolder, int i) { } } + /** + * Override method of RecyclerView.Adapter class. + * + * This returns the count of views required. + */ @Override public int getItemCount() { return dataMap.size(); } + /** + * Class to hold views inflated by the adapterLayout. + */ public class SuperViewHolder extends RecyclerView.ViewHolder { public SuperViewHolder(@NonNull View itemView) { @@ -77,6 +135,16 @@ public SuperViewHolder(@NonNull View itemView) { } } + /** + * Method to find and return all child views present in + * adapterLayout to finally add them in viewList. + * + * @param v The View is the view generated by the LayoutInflator + * in onBindViewHolder, through which we get all the + * child views in the layout and add them to viewList. + * + * @return result The child view list is returned. + */ public List getAllChildren(View v) { if (!(v instanceof ViewGroup)) { @@ -94,7 +162,10 @@ public List getAllChildren(View v) { return result; } - public Map getViewsList() { + /** + * Incomplete Method to get viewList. + */ + private Map getViewsList() { Map views = new HashMap<>(); for (int i = 0; i < viewList.size(); i++) { T view = (T) viewList.get(i); @@ -103,15 +174,45 @@ public Map getViewsList() { return views; } + /** + * Method to set CreamAdapterListener on CreamAdapter object. + * + * @param listener The Listener is set to the member variable listener + * which was earlier set to null. + */ public void setCreamAdapterListener(CreamAdapterListener listener) { this.listener = listener; } + /** + * Public interface to create CreamAdapterListner. + */ public interface CreamAdapterListener { + + /** + * Method provides current position of the candy view + * & child views in that adapter view. + * + * @param view The View gives all the views recycled for + * a position. + * @param position The int gives the current position of + * the candy view. + */ void onNewPosition(View view, int position); + + /** + * Method which is called as soon as the layout is + * inflated and child views are added to viewList. + */ void onFinishInit(); } + /** + * Method to return View of the required view_id. + * + * @param id The ID of the view whose view is to + * be returned. + */ public View getViewById(@NonNull final int id) { for (int i = 0; i < viewList.size(); i++) { if (viewList.get(i).getId() == id)