Fixes: #3278: Add java docs to methods which have it missing (#3351)

* achievements/: add Javadocs

* actions/: add Javadocs

* WikiAccountAuthenticator: add Javadocs

* ReasonBuilder: add Javadocs

* di: Add javadocs to DI files

* bookmarks: add Javadocs to bookmarks files

* di: Added more Javadocs

* file: add Javadocs for file picker

* actions: add proper decription to the classes

Author: kbhardwaj123

app/src/main/java/fr/free/nrw/commons/achievements/AchievementsActivity.java

@@ -169,9 +169,13 @@ public boolean onCreateOptionsMenu(Menu menu) {
         return true;
     }
 
+    /**
+     * To receive the id of selected item and handle further logic for that selected item
+     */
     @Override
     public boolean onOptionsItemSelected(MenuItem item) {
         int id = item.getItemId();
+        // take screenshot in form of bitmap and show it in Alert Dialog
         if (id == R.id.share_app_icon) {
             View rootView = getWindow().getDecorView().findViewById(android.R.id.content);
             Bitmap screenShot = Utils.getScreenShot(rootView);
@@ -241,20 +245,29 @@ private void setAchievements() {
         }
     }
 
+    /**
+     * To call the API to fetch the count of wiki data edits
+     *  in the form of JavaRx Single object<JSONobject>
+     */
     @SuppressLint("CheckResult")
     private void setWikidataEditCount() {
         String userName = sessionManager.getUserName();
         if (StringUtils.isBlank(userName)) {
             return;
         }
-        compositeDisposable.add(okHttpJsonApiClient.getWikidataEdits(userName)
+        compositeDisposable.add(okHttpJsonApiClient
+                .getWikidataEdits(userName)
                 .subscribeOn(Schedulers.io())
                 .observeOn(AndroidSchedulers.mainThread())
                 .subscribe(edits -> wikidataEditsText.setText(String.valueOf(edits)), e -> {
                     Timber.e("Error:" + e);
                 }));
     }
 
+    /**
+     * Shows a snack bar which has an action button which on click dismisses the snackbar and invokes the
+     * listener passed
+     */
     private void showSnackBarWithRetry() {
         progressBar.setVisibility(View.GONE);
         ViewUtil.showDismissibleSnackBar(findViewById(android.R.id.content),

app/src/main/java/fr/free/nrw/commons/achievements/FeaturedImages.kt

@@ -2,4 +2,11 @@ package fr.free.nrw.commons.achievements
 
 import com.google.gson.annotations.SerializedName
 
-class FeaturedImages(@field:SerializedName("Quality_images") val qualityImages: Int, @field:SerializedName("Featured_pictures_on_Wikimedia_Commons") val featuredPicturesOnWikimediaCommons: Int)
+/**
+* Represents Featured Images on WikiMedia Commons platform
+* Used by Achievements and FeedbackResponse (objects) of the user
+*/
+class FeaturedImages(
+    @field:SerializedName("Quality_images") val qualityImages: Int,
+    @field:SerializedName("Featured_pictures_on_Wikimedia_Commons") val featuredPicturesOnWikimediaCommons: Int
+)

app/src/main/java/fr/free/nrw/commons/achievements/FeedbackResponse.kt

@@ -1,5 +1,8 @@
 package fr.free.nrw.commons.achievements
 
+/**
+* Represent the Feedback Response of the user
+*/
 data class FeedbackResponse(val uniqueUsedImages: Int,
                             val articlesUsingImages: Int,
                             val deletedUploads: Int,

app/src/main/java/fr/free/nrw/commons/actions/PageEditClient.java

@@ -5,6 +5,13 @@
 
 import io.reactivex.Observable;
 
+/**
+ * This class acts as a Client to facilitate wiki page editing
+ * services to various dependency providing modules such as the Network module, the Review Controller ,etc
+ * 
+ * The methods provided by this class will post to the Media wiki api
+ * documented at: https://commons.wikimedia.org/w/api.php?action=help&modules=edit
+ */
 public class PageEditClient {
 
     private final CsrfTokenClient csrfTokenClient;
@@ -19,6 +26,12 @@ public PageEditClient(CsrfTokenClient csrfTokenClient,
         this.service = service;
     }
 
+    /**
+     * This method is used when the content of the page is to be replaced by new content received
+     * @param pagetitle   Title of the page to edit
+     * @param text        Holds the page content
+     * @param summary     Edit summary
+     */
     public Observable<Boolean> edit(String pageTitle, String text, String summary) {
         try {
             return pageEditInterface.postEdit(pageTitle, summary, text, csrfTokenClient.getTokenBlocking())
@@ -28,6 +41,12 @@ public Observable<Boolean> edit(String pageTitle, String text, String summary) {
         }
     }
 
+    /**
+     * This method is used when we need to append something to the end of wiki page content
+     * @param pagetitle   Title of the page to edit
+     * @param appendText  The received page content is added to beginning of the page
+     * @param summary     Edit summary
+     */
     public Observable<Boolean> appendEdit(String pageTitle, String appendText, String summary) {
         try {
             return pageEditInterface.postAppendEdit(pageTitle, summary, appendText, csrfTokenClient.getTokenBlocking())
@@ -37,6 +56,12 @@ public Observable<Boolean> appendEdit(String pageTitle, String appendText, Strin
         }
     }
 
+    /**
+     * This method is used when we need to add something to the starting of the page
+     * @param pagetitle   Title of the page to edit
+     * @param prependText The received page content is added to beginning of the page
+     * @param summary     Edit summary
+     */
     public Observable<Boolean> prependEdit(String pageTitle, String prependText, String summary) {
         try {
             return pageEditInterface.postPrependEdit(pageTitle, summary, prependText, csrfTokenClient.getTokenBlocking())

app/src/main/java/fr/free/nrw/commons/actions/PageEditInterface.java

@@ -12,17 +12,43 @@
 
 import static org.wikipedia.dataclient.Service.MW_API_PREFIX;
 
+/**
+ * This interface facilitates wiki commons page editing services to the Networking module
+ * which provides all network related services used by the app.
+ * 
+ * This interface posts a form encoded request to the wikimedia API 
+ * with editing action as argument to edit a particular page
+ */
 public interface PageEditInterface {
 
+    /**
+     * This method posts such that the Content which the page
+     * has will be completely replaced by the value being passed to the
+     * "text" field of the encoded form data
+     * @param title    Title of the page to edit. Cannot be used together with pageid.
+     * @param summary  Edit summary. Also section title when section=new and sectiontitle is not set
+     * @param text     Holds the page content
+     * @param token    A "csrf" token
+     */
     @FormUrlEncoded
     @Headers("Cache-Control: no-cache")
     @POST(MW_API_PREFIX + "action=edit")
     @NonNull
     Observable<Edit> postEdit(@NonNull @Field("title") String title,
                               @NonNull @Field("summary") String summary,
                               @NonNull @Field("text") String text,
+                              // NOTE: This csrf shold always be sent as the last field of form data
                               @NonNull @Field("token") String token);
 
+                              /**
+     * This method posts such that the Content which the page
+     * has will be completely replaced by the value being passed to the
+     * "text" field of the encoded form data
+     * @param title    Title of the page to edit. Cannot be used together with pageid.
+     * @param summary  Edit summary. Also section title when section=new and sectiontitle is not set
+     * @param text     The received page content is added to beginning of the page
+     * @param token    A "csrf" token
+     */
     @FormUrlEncoded
     @Headers("Cache-Control: no-cache")
     @POST(MW_API_PREFIX + "action=edit")
@@ -31,6 +57,15 @@ Observable<Edit> postEdit(@NonNull @Field("title") String title,
                                              @NonNull @Field("appendtext") String text,
                                              @NonNull @Field("token") String token);
 
+                                             /**
+     * This method posts such that the Content which the page
+     * has will be completely replaced by the value being passed to the
+     * "text" field of the encoded form data
+     * @param title    Title of the page to edit. Cannot be used together with pageid.
+     * @param summary  Edit summary. Also section title when section=new and sectiontitle is not set
+     * @param text     The received page content is added to beginning of the page
+     * @param token    A "csrf" token
+     */
     @FormUrlEncoded
     @Headers("Cache-Control: no-cache")
     @POST(MW_API_PREFIX + "action=edit")

app/src/main/java/fr/free/nrw/commons/actions/ThanksClient.java

@@ -10,6 +10,13 @@
 import fr.free.nrw.commons.CommonsApplication;
 import io.reactivex.Observable;
 
+/**
+ * Facilitates the Wkikimedia Thanks api extention, as described in the 
+ * api documentation: "The Thanks extension includes an API for sending thanks"
+ * 
+ * In simple terms this class is used by a user to thank someone for adding 
+ * contribution to the commons platform
+ */
 @Singleton
 public class ThanksClient {
 
@@ -23,6 +30,11 @@ public ThanksClient(@Named("commons-csrf") CsrfTokenClient csrfTokenClient,
         this.service = service;
     }
 
+    /**
+     * Handles the Thanking logic
+     * @param revesionID The revision ID you would like to thank someone for
+     * @return if thanks was successfully sent to intended recepient, returned as a boolean observable
+     */
     public Observable<Boolean> thank(long revisionId) {
         try {
             return service.thank(String.valueOf(revisionId), null,

app/src/main/java/fr/free/nrw/commons/auth/WikiAccountAuthenticator.java

@@ -17,6 +17,9 @@
 
 import static fr.free.nrw.commons.auth.AccountUtil.AUTH_TOKEN_TYPE;
 
+/**
+ * Handles WikiMedia commons account Authentication
+ */
 public class WikiAccountAuthenticator extends AbstractAccountAuthenticator {
     private static final String[] SYNC_AUTHORITIES = {BuildConfig.CONTRIBUTION_AUTHORITY, BuildConfig.MODIFICATION_AUTHORITY};
 
@@ -28,6 +31,9 @@ public WikiAccountAuthenticator(@NonNull Context context) {
         this.context = context;
     }
 
+    /**
+     * Provides Bundle with edited Account Properties 
+     */
     @Override
     public Bundle editProperties(AccountAuthenticatorResponse response, String accountType) {
         Bundle bundle = new Bundle();
@@ -40,7 +46,7 @@ public Bundle addAccount(@NonNull AccountAuthenticatorResponse response,
                              @NonNull String accountType, @Nullable String authTokenType,
                              @Nullable String[] requiredFeatures, @Nullable Bundle options)
             throws NetworkErrorException {
-
+        // account type not supported returns bundle without loginActivity Intent, it just contains "test" key 
         if (!supportedAccountType(accountType)) {
             Bundle bundle = new Bundle();
             bundle.putString("test", "addAccount");
@@ -100,6 +106,10 @@ private boolean supportedAccountType(@Nullable String type) {
         return BuildConfig.ACCOUNT_TYPE.equals(type);
     }
 
+    /**
+     * Provides a bundle containing a Parcel 
+     * the Parcel packs an Intent with LoginActivity and Authenticator response (requires valid account type)
+     */
     private Bundle addAccount(AccountAuthenticatorResponse response) {
         Intent intent = new Intent(context, LoginActivity.class);
         intent.putExtra(AccountManager.KEY_ACCOUNT_AUTHENTICATOR_RESPONSE, response);

app/src/main/java/fr/free/nrw/commons/auth/WikiAccountAuthenticatorService.java

@@ -8,6 +8,10 @@
 
 import fr.free.nrw.commons.di.CommonsDaggerService;
 
+/**
+ * Handles the Auth service of the App, see AndroidManifests for details
+ * (Uses Dagger 2 as injector)
+ */
 public class WikiAccountAuthenticatorService extends CommonsDaggerService {
 
     @Nullable

app/src/main/java/fr/free/nrw/commons/bookmarks/locations/BookmarkLocationsContentProvider.java

@@ -4,6 +4,7 @@
 import android.database.Cursor;
 import android.database.sqlite.SQLiteDatabase;
 import android.database.sqlite.SQLiteQueryBuilder;
+// We can get uri using java.Net.Uri, but andoid implimentation is faster (but it's forgiving with handling exceptions though)
 import android.net.Uri;
 import android.text.TextUtils;
 
@@ -19,11 +20,17 @@
 import static fr.free.nrw.commons.bookmarks.locations.BookmarkLocationsDao.Table.COLUMN_NAME;
 import static fr.free.nrw.commons.bookmarks.locations.BookmarkLocationsDao.Table.TABLE_NAME;
 
+/**
+ * Handles private storage for Bookmark locations
+ */
 public class BookmarkLocationsContentProvider extends CommonsDaggerContentProvider {
 
     private static final String BASE_PATH = "bookmarksLocations";
     public static final Uri BASE_URI = Uri.parse("content://" + BuildConfig.BOOKMARK_LOCATIONS_AUTHORITY + "/" + BASE_PATH);
 
+    /**
+     * Append bookmark locations name to the base uri 
+     */
     public static Uri uriForName(String name) {
         return Uri.parse(BASE_URI.toString() + "/" + name);
     }
@@ -35,6 +42,14 @@ public String getType(@NonNull Uri uri) {
         return null;
     }
 
+    /**
+     * Queries the SQLite database for the bookmark locations
+     * @param uri : contains the uri for bookmark locations
+     * @param projection
+     * @param selection : handles Where
+     * @param selectionArgs : the condition of Where clause
+     * @param sortOrder : ascending or descending
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public Cursor query(@NonNull Uri uri, String[] projection, String selection,
@@ -49,6 +64,13 @@ public Cursor query(@NonNull Uri uri, String[] projection, String selection,
         return cursor;
     }
 
+    /**
+     * Handles the update query of local SQLite Database 
+     * @param uri : contains the uri for bookmark locations
+     * @param contentValues : new values to be entered to db
+     * @param selection : handles Where
+     * @param selectionArgs : the condition of Where clause
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public int update(@NonNull Uri uri, ContentValues contentValues, String selection,
@@ -69,6 +91,9 @@ public int update(@NonNull Uri uri, ContentValues contentValues, String selectio
         return rowsUpdated;
     }
 
+    /**
+     * Handles the insertion of new bookmark locations record to local SQLite Database
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public Uri insert(@NonNull Uri uri, ContentValues contentValues) {

app/src/main/java/fr/free/nrw/commons/bookmarks/pictures/BookmarkPicturesContentProvider.java

@@ -4,6 +4,7 @@
 import android.database.Cursor;
 import android.database.sqlite.SQLiteDatabase;
 import android.database.sqlite.SQLiteQueryBuilder;
+// We can get uri using java.Net.Uri, but andoid implimentation is faster (but it's forgiving with handling exceptions though)
 import android.net.Uri;
 import android.text.TextUtils;
 
@@ -19,11 +20,17 @@
 import static fr.free.nrw.commons.bookmarks.pictures.BookmarkPicturesDao.Table.COLUMN_MEDIA_NAME;
 import static fr.free.nrw.commons.bookmarks.pictures.BookmarkPicturesDao.Table.TABLE_NAME;
 
+/**
+ * Handles private storage for Bookmark pictures
+ */
 public class BookmarkPicturesContentProvider extends CommonsDaggerContentProvider {
 
     private static final String BASE_PATH = "bookmarks";
     public static final Uri BASE_URI = Uri.parse("content://" + BuildConfig.BOOKMARK_AUTHORITY + "/" + BASE_PATH);
 
+    /**
+     * Append bookmark pictures name to the base uri 
+     */
     public static Uri uriForName(String name) {
         return Uri.parse(BASE_URI.toString() + "/" + name);
     }
@@ -36,6 +43,14 @@ public String getType(@NonNull Uri uri) {
         return null;
     }
 
+    /**
+     * Queries the SQLite database for the bookmark pictures
+     * @param uri : contains the uri for bookmark pictures
+     * @param projection
+     * @param selection : handles Where
+     * @param selectionArgs : the condition of Where clause
+     * @param sortOrder : ascending or descending
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public Cursor query(@NonNull Uri uri, String[] projection, String selection,
@@ -50,6 +65,13 @@ public Cursor query(@NonNull Uri uri, String[] projection, String selection,
         return cursor;
     }
 
+    /**
+     * Handles the update query of local SQLite Database 
+     * @param uri : contains the uri for bookmark pictures
+     * @param contentValues : new values to be entered to db
+     * @param selection : handles Where
+     * @param selectionArgs : the condition of Where clause
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public int update(@NonNull Uri uri, ContentValues contentValues, String selection,
@@ -70,6 +92,9 @@ public int update(@NonNull Uri uri, ContentValues contentValues, String selectio
         return rowsUpdated;
     }
 
+    /**
+     * Handles the insertion of new bookmark pictures record to local SQLite Database
+     */
     @SuppressWarnings("ConstantConditions")
     @Override
     public Uri insert(@NonNull Uri uri, ContentValues contentValues) {

app/src/main/java/fr/free/nrw/commons/category/CategoriesRenderer.java

@@ -12,6 +12,9 @@
 import fr.free.nrw.commons.R;
 import timber.log.Timber;
 
+/**
+ * Renders the Categories view
+ */
 public class CategoriesRenderer extends Renderer<CategoryItem> {
     @BindView(R.id.tvName) CheckedTextView checkedView;
     private final CategoryClickedListener listener;