Merge pull request #1025 from prajgov/master

Added JavaDoc comments to few methods and classes

app/src/main/java/fr/free/nrw/commons/AboutActivity.java

@@ -8,10 +8,18 @@ import butterknife.ButterKnife;
 import fr.free.nrw.commons.theme.NavigationBaseActivity;
 import fr.free.nrw.commons.ui.widget.HtmlTextView;
 
+/**
+ * Represents about screen of this app
+ */
 public class AboutActivity extends NavigationBaseActivity {
     @BindView(R.id.about_version) TextView versionText;
     @BindView(R.id.about_license) HtmlTextView aboutLicenseText;
 
+    /**
+     * This method helps in the creation About screen
+     *
+     * @param savedInstanceState Data bundle
+     */
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);

app/src/main/java/fr/free/nrw/commons/CommonsApplication.java

@@ -53,12 +53,17 @@ public class CommonsApplication extends DaggerApplication {
     public static final String DEFAULT_EDIT_SUMMARY = "Uploaded using Android Commons app";
     
     public static final String FEEDBACK_EMAIL = "commons-app-android@googlegroups.com";
+    
     public static final String LOGS_PRIVATE_EMAIL = "commons-app-android-private@googlegroups.com";
+    
     public static final String FEEDBACK_EMAIL_SUBJECT = "Commons Android App (%s) Feedback";
     
     private CommonsApplicationComponent component;
     private RefWatcher refWatcher;
 
+    /**
+     * Used to declare and initialize various components and dependencies
+     */
     @Override
     public void onCreate() {
         super.onCreate();
@@ -80,6 +85,10 @@ public class CommonsApplication extends DaggerApplication {
         System.setProperty("in.yuvi.http.fluent.PROGRESS_TRIGGER_THRESHOLD", "3.0");
     }
 
+    /**
+     * Helps in setting up LeakCanary library
+     * @return instance of LeakCanary
+     */
     protected RefWatcher setupLeakCanary() {
         if (LeakCanary.isInAnalyzerProcess(this)) {
             return RefWatcher.DISABLED;
@@ -87,16 +96,30 @@ public class CommonsApplication extends DaggerApplication {
         return LeakCanary.install(this);
     }
     
+  /**
+     * Provides a way to get member refWatcher
+     *
+     * @param context Application context
+     * @return application member refWatcher
+     */
     public static RefWatcher getRefWatcher(Context context) {
         CommonsApplication application = (CommonsApplication) context.getApplicationContext();
         return application.refWatcher;
     }
     
+    /**
+    * Helps in injecting dependency library Dagger
+    * @return Dagger injector
+    */
     @Override
-     protected AndroidInjector<? extends DaggerApplication> applicationInjector() {
+    protected AndroidInjector<? extends DaggerApplication> applicationInjector() {
         return injector();
     }
 
+    /**
+     * used to create injector of application component
+     * @return Application component of Dagger
+     */
     public CommonsApplicationComponent injector() {
         if (component == null) {
             component = DaggerCommonsApplicationComponent.builder()
@@ -106,6 +129,11 @@ public class CommonsApplication extends DaggerApplication {
         return component;
     }
 
+    /**
+     * clears data of current application
+     * @param context Application context
+     * @param logoutListener Implementation of interface LogoutListener
+     */
     public void clearApplicationData(Context context, LogoutListener logoutListener) {
         File cacheDirectory = context.getCacheDir();
         File applicationDirectory = new File(cacheDirectory.getParent());
@@ -145,6 +173,9 @@ public class CommonsApplication extends DaggerApplication {
         Contribution.Table.onDelete(db);
     }
 
+    /**
+     * Interface used to get log-out events
+     */
     public interface LogoutListener {
         void onLogoutComplete();
     }

app/src/main/java/fr/free/nrw/commons/License.java

@@ -2,6 +2,9 @@ package fr.free.nrw.commons;
 
 import android.support.annotation.Nullable;
 
+/**
+ * represents Licence object
+ */
 public class License {
     private String key;
     private String template;
@@ -56,6 +59,12 @@ public class License {
         }
     }
 
+    /**
+     * Gets the license URL
+     *
+     * @param language license language
+     * @return URL
+     */
     public @Nullable String getUrl(String language) {
         if (url == null) {
             return null;

app/src/main/java/fr/free/nrw/commons/LicenseList.java

@@ -13,10 +13,18 @@ import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
 
+/**
+ * Represents a list of Licenses
+ */
 public class LicenseList {
     private Map<String, License> licenses = new HashMap<>();
     private Resources res;
 
+    /**
+     * Constructs new instance of LicenceList
+     *
+     * @param activity License activity
+     */
     public LicenseList(Activity activity) {
         res = activity.getResources();
         XmlPullParser parser = res.getXml(R.xml.wikimedia_licenses);
@@ -31,14 +39,28 @@ public class LicenseList {
         }
     }
 
+    /**
+     * Gets a collection of licenses
+     * @return License values
+     */
     public Collection<License> values() {
         return licenses.values();
     }
 
+    /**
+     * Gets license
+     * @param key License key
+     * @return License that matches key
+     */
     public License get(String key) {
         return licenses.get(key);
     }
 
+    /**
+     * Creates a license from template
+     * @param template License template
+     * @return null
+     */
     @Nullable
     License licenseForTemplate(String template) {
         String ucTemplate = new PageTitle(template).getDisplayText();
@@ -50,6 +72,11 @@ public class LicenseList {
         return null;
     }
 
+    /**
+     * Gets template name id
+     * @param template License template
+     * @return name id of template
+     */
     private String nameIdForTemplate(String template) {
         // hack :D (converts dashes and periods to underscores)
         // cc-by-sa-3.0 -> cc_by_sa_3_0
@@ -57,6 +84,11 @@ public class LicenseList {
                 "_").replace(".", "_");
     }
 
+    /**
+     * Gets name of given template
+     * @param template License template
+     * @return name of template
+     */
     private String nameForTemplate(String template) {
         int nameId = res.getIdentifier("fr.free.nrw.commons:string/"
                 + nameIdForTemplate(template), null, null);

app/src/main/java/fr/free/nrw/commons/Media.java

@@ -47,16 +47,35 @@ public class Media implements Parcelable {
     private HashMap<String, Object> tags = new HashMap<>();
     private @Nullable LatLng coordinates;
 
+    /**
+     * Provides local constructor
+     */
     protected Media() {
         this.categories = new ArrayList<>();
         this.descriptions = new HashMap<>();
     }
 
+    /**
+     * Provides a minimal constructor
+     *
+     * @param filename Media filename
+     */
     public Media(String filename) {
         this();
         this.filename = filename;
     }
 
+    /**
+     * Provide Media constructor
+     * @param localUri Media URI
+     * @param imageUrl Media image URL
+     * @param filename Media filename
+     * @param description Media description
+     * @param dataLength Media date length
+     * @param dateCreated Media creation date
+     * @param dateUploaded Media date uploaded
+     * @param creator Media creator
+     */
     public Media(Uri localUri, String imageUrl, String filename, String description,
                  long dataLength, Date dateCreated, @Nullable Date dateUploaded, String creator) {
         this();
@@ -90,19 +109,33 @@ public class Media implements Parcelable {
         descriptions = in.readHashMap(ClassLoader.getSystemClassLoader());
     }
 
+    /**
+     * Gets tag of media
+     * @param key Media key
+     * @return Media tag
+     */
     public Object getTag(String key) {
         return tags.get(key);
     }
 
+    /**
+     * Modifies( or creates a) tag of media
+     * @param key Media key
+     * @param value Media value
+     */
     public void setTag(String key, Object value) {
         tags.put(key, value);
     }
 
+    /**
+     * Gets media display title
+     * @return Media title
+     */
     public String getDisplayTitle() {
         if (filename == null) {
             return "";
         }
-        // FIXME: Gross hack bercause my regex skills suck maybe or I am too lazy who knows
+        // FIXME: Gross hack because my regex skills suck maybe or I am too lazy who knows
         String title = getFilePageTitle().getDisplayText().replaceFirst("^File:", "");
         Matcher matcher = displayTitlePattern.matcher(title);
         if (matcher.matches()) {
@@ -112,14 +145,27 @@ public class Media implements Parcelable {
         }
     }
 
+    /**
+     * Gets file page title
+     * @return New media page title
+     */
     public PageTitle getFilePageTitle() {
         return new PageTitle("File:" + getFilename().replaceFirst("^File:", ""));
     }
 
+    /**
+     * Gets local URI
+     * @return Media local URI
+     */
     public Uri getLocalUri() {
         return localUri;
     }
 
+    /**
+     * Gets image URL
+     * can be null.
+     * @return Image URL
+     */
     @Nullable
     public String getImageUrl() {
         if (imageUrl == null && this.getFilename() != null) {
@@ -304,6 +350,10 @@ public class Media implements Parcelable {
         this.categories.addAll(categories);
     }
 
+    /**
+     * Modifies (or sets) media descriptions
+     * @param descriptions Media descriptions
+     */
     void setDescriptions(Map<String, String> descriptions) {
         for (String key : this.descriptions.keySet()) {
             this.descriptions.remove(key);
@@ -313,6 +363,11 @@ public class Media implements Parcelable {
         }
     }
 
+    /**
+     * Gets media description in preferred language
+     * @param preferredLanguage Language preferred
+     * @return Description in preferred language
+     */
     public String getDescription(String preferredLanguage) {
         if (descriptions.containsKey(preferredLanguage)) {
             // See if the requested language is there.
@@ -329,11 +384,21 @@ public class Media implements Parcelable {
         }
     }
 
+    /**
+     * Method of Parcelable interface
+     * @return zero
+     */
     @Override
     public int describeContents() {
         return 0;
     }
 
+    /**
+     * Creates a way to transfer information between two or more
+     * activities.
+     * @param parcel Instance of Parcel
+     * @param flags Parcel flag
+     */
     @Override
     public void writeToParcel(Parcel parcel, int flags) {
         parcel.writeParcelable(localUri, flags);

app/src/main/java/fr/free/nrw/commons/Utils.java

@@ -37,12 +37,23 @@ public class Utils {
         }
     }
 
+    /**
+     * Creates an URL for thumbnail
+     *
+     * @param filename Thumbnail file name
+     * @return URL of thumbnail
+     */
     public static String makeThumbBaseUrl(@NonNull String filename) {
         String name = new PageTitle(filename).getPrefixedText();
         String sha = new String(Hex.encodeHex(DigestUtils.md5(name)));
         return String.format("%s/%s/%s/%s", BuildConfig.IMAGE_URL_BASE, sha.substring(0, 1), sha.substring(0, 2), urlEncode(name));
     }
 
+    /**
+     * URL Encode an URL in UTF-8 format
+     * @param url Unformatted URL
+     * @return Encoded URL
+     */
     public static String urlEncode(String url) {
         try {
             return URLEncoder.encode(url, "utf-8");
@@ -61,6 +72,11 @@ public class Utils {
         return string.substring(0, 1).toUpperCase(Locale.getDefault()) + string.substring(1);
     }
 
+    /**
+     * Generates licence name with given ID
+     * @param license License ID
+     * @return Name of license
+     */
     public static int licenseNameFor(String license) {
         switch (license) {
             case Prefs.Licenses.CC_BY_3:
@@ -81,6 +97,12 @@ public class Utils {
         throw new RuntimeException("Unrecognized license value: " + license);
     }
 
+    /**
+     * Fixing incorrect extension
+     * @param title File name
+     * @param extension Correct extension
+     * @return File with correct extension
+     */
     public static String fixExtension(String title, String extension) {
         Pattern jpegPattern = Pattern.compile("\\.jpeg$", Pattern.CASE_INSENSITIVE);
 
@@ -96,6 +118,11 @@ public class Utils {
         return title;
     }
 
+    /**
+     * Tells whether dark theme is active or not
+     * @param context Activity context
+     * @return The state of dark theme
+     */
     public static boolean isDarkTheme(Context context) {
         return PreferenceManager.getDefaultSharedPreferences(context).getBoolean("theme", false);
     }

app/src/main/java/fr/free/nrw/commons/WelcomeActivity.java

@@ -18,6 +18,11 @@ public class WelcomeActivity extends BaseActivity {
 
     private WelcomePagerAdapter adapter = new WelcomePagerAdapter();
 
+    /**
+     * Initialises exiting fields and dependencies
+     *
+     * @param savedInstanceState WelcomeActivity bundled data
+     */
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -30,12 +35,20 @@ public class WelcomeActivity extends BaseActivity {
         adapter.setCallback(this::finish);
     }
 
+    /**
+     * References WelcomePageAdapter to null before the activity is destroyed
+     */
     @Override
     public void onDestroy() {
         adapter.setCallback(null);
         super.onDestroy();
     }
 
+    /**
+     * Creates a way to change current activity to WelcomeActivity
+     *
+     * @param context Activity context
+     */
     public static void startYourself(Context context) {
         Intent welcomeIntent = new Intent(context, WelcomeActivity.class);
         context.startActivity(welcomeIntent);

app/src/main/java/fr/free/nrw/commons/WelcomePagerAdapter.java

@@ -10,13 +10,6 @@ import butterknife.ButterKnife;
 import butterknife.OnClick;
 
 public class WelcomePagerAdapter extends PagerAdapter {
-    private static final int PAGE_FINAL = 4;
-    private Callback callback;
-
-    public interface Callback {
-        void onYesClicked();
-    }
-
     static final int[] PAGE_LAYOUTS = new int[]{
             R.layout.welcome_wikipedia,
             R.layout.welcome_do_upload,
@@ -24,16 +17,34 @@ public class WelcomePagerAdapter extends PagerAdapter {
             R.layout.welcome_image_details,
             R.layout.welcome_final
     };
+    private static final int PAGE_FINAL = 4;
+    private Callback callback;
 
+    /**
+     * Changes callback to provided one
+     *
+     * @param callback New callback
+     *                 it can be null.
+     */
     public void setCallback(@Nullable Callback callback) {
         this.callback = callback;
     }
 
+    /**
+     * Gets total number of layouts
+     * @return Number of layouts
+     */
     @Override
     public int getCount() {
         return PAGE_LAYOUTS.length;
     }
 
+    /**
+     * Compares given view with provided object
+     * @param view Adapter view
+     * @param object Adapter object
+     * @return Equality between view and object
+     */
     @Override
     public boolean isViewFromObject(View view, Object object) {
         return (view == object);
@@ -52,16 +63,29 @@ public class WelcomePagerAdapter extends PagerAdapter {
         return layout;
     }
 
+    /**
+     * Provides a way to remove an item from container
+     * @param container Adapter view group container
+     * @param position Index of item
+     * @param obj Adapter object
+     */
     @Override
     public void destroyItem(ViewGroup container, int position, Object obj) {
         container.removeView((View) obj);
     }
 
+    public interface Callback {
+        void onYesClicked();
+    }
+
     class ViewHolder {
         ViewHolder(View view) {
             ButterKnife.bind(this, view);
         }
 
+        /**
+         * Triggers on click callback on button click
+         */
         @OnClick(R.id.welcomeYesButton)
         void onClicked() {
             if (callback != null) {

app/src/main/java/fr/free/nrw/commons/data/Category.java

@@ -14,6 +14,9 @@ import java.util.Date;
 
 import fr.free.nrw.commons.category.CategoryContentProvider;
 
+/**
+ * Represents a category
+ */
 public class Category {
     private Uri contentUri;
 
@@ -22,36 +25,72 @@ public class Category {
     private int timesUsed;
 
     // Getters/setters
+    /**
+     * Gets name
+     *
+     * @return name
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Modifies name
+     *
+     * @param name Category name
+     */
     public void setName(String name) {
         this.name = name;
     }
 
+    /**
+     * Gets last used date
+     *
+     * @return Last used date
+     */
     private Date getLastUsed() {
         // warning: Date objects are mutable.
         return (Date)lastUsed.clone();
     }
 
+    /**
+     * Modifies last used date
+     *
+     * @param lastUsed Category date
+     */
     public void setLastUsed(Date lastUsed) {
         // warning: Date objects are mutable.
         this.lastUsed = (Date)lastUsed.clone();
     }
 
+    /**
+     * Generates new last used date
+     */
     private void touch() {
         lastUsed = new Date();
     }
 
+    /**
+     * Gets no. of times the category is used
+     *
+     * @return no. of times used
+     */
     private int getTimesUsed() {
         return timesUsed;
     }
 
+    /**
+     * Modifies no. of times used
+     *
+     * @param timesUsed Category used times
+     */
     public void setTimesUsed(int timesUsed) {
         this.timesUsed = timesUsed;
     }
 
+    /**
+     * Increments timesUsed by 1 and sets last used date as now.
+     */
     public void incTimesUsed() {
         timesUsed++;
         touch();
@@ -75,6 +114,11 @@ public class Category {
         }
     }
 
+    /**
+     * Gets content values
+     *
+     * @return Content values
+     */
     private ContentValues toContentValues() {
         ContentValues cv = new ContentValues();
         cv.put(Table.COLUMN_NAME, getName());
@@ -83,6 +127,11 @@ public class Category {
         return cv;
     }
 
+    /**
+     * Gets category from cursor
+     * @param cursor Category cursor
+     * @return Category from cursor
+     */
     private static Category fromCursor(Cursor cursor) {
         // Hardcoding column positions!
         Category c = new Category();
@@ -175,15 +224,30 @@ public class Category {
                 + COLUMN_TIMES_USED + " INTEGER"
                 + ");";
 
+        /**
+         * Creates new table with provided SQLite database
+         *
+         * @param db Category database
+         */
         public static void onCreate(SQLiteDatabase db) {
             db.execSQL(CREATE_TABLE_STATEMENT);
         }
 
+        /**
+         * Deletes existing table
+         * @param db Category database
+         */
         public static void onDelete(SQLiteDatabase db) {
             db.execSQL("DROP TABLE IF EXISTS " + TABLE_NAME);
             onCreate(db);
         }
 
+        /**
+         * Updates given database
+         * @param db Category database
+         * @param from Exiting category id
+         * @param to New category id
+         */
         public static void onUpdate(SQLiteDatabase db, int from, int to) {
             if (from == to) {
                 return;

app/src/main/java/fr/free/nrw/commons/mwapi/LogBuilder.java

@@ -22,6 +22,14 @@ public class LogBuilder {
     private final String schema;
     private final SharedPreferences prefs;
 
+    /**
+     * Main constructor of LogBuilder
+     *
+     * @param schema   Log schema
+     * @param revision Log revision
+     * @param mwApi    Wiki media API instance
+     * @param prefs    Instance of SharedPreferences
+     */
     LogBuilder(String schema, long revision, MediaWikiApi mwApi, SharedPreferences prefs) {
         this.prefs = prefs;
         this.data = new JSONObject();
@@ -30,6 +38,12 @@ public class LogBuilder {
         this.mwApi = mwApi;
     }
 
+    /**
+     * Adds data to preferences
+     * @param key Log key
+     * @param value Log object value
+     * @return LogBuilder
+     */
     public LogBuilder param(String key, Object value) {
         try {
             data.put(key, value);
@@ -39,6 +53,10 @@ public class LogBuilder {
         return this;
     }
 
+    /**
+     * Encodes JSON object to URL
+     * @return URL to JSON object
+     */
     URL toUrl() {
         JSONObject fullData = new JSONObject();
         try {

app/src/main/java/fr/free/nrw/commons/mwapi/LogTask.java

@@ -6,10 +6,20 @@ class LogTask extends AsyncTask<LogBuilder, Void, Boolean> {
 
     private final MediaWikiApi mwApi;
 
+    /**
+     * Main constructor of LogTask
+     *
+     * @param mwApi Media wiki API instance
+     */
     public LogTask(MediaWikiApi mwApi) {
         this.mwApi = mwApi;
     }
 
+    /**
+     * Logs events in background
+     * @param logBuilders LogBuilder instance
+     * @return Background success state ( TRUE or FALSE )
+     */
     @Override
     protected Boolean doInBackground(LogBuilder... logBuilders) {
         return mwApi.logEvents(logBuilders);

app/src/main/java/fr/free/nrw/commons/mwapi/MediaResult.java

@@ -4,15 +4,29 @@ public class MediaResult {
     private final String wikiSource;
     private final String parseTreeXmlSource;
 
+    /**
+     * Full-fledged constructor of MediaResult
+     *
+     * @param wikiSource         Media wiki source
+     * @param parseTreeXmlSource Media tree parsed in XML
+     */
     MediaResult(String wikiSource, String parseTreeXmlSource) {
         this.wikiSource = wikiSource;
         this.parseTreeXmlSource = parseTreeXmlSource;
     }
 
+    /**
+     * Gets wiki source
+     * @return Wiki source
+     */
     public String getWikiSource() {
         return wikiSource;
     }
 
+    /**
+     * Gets tree parsed in XML
+     * @return XML parsed tree
+     */
     public String getParseTreeXmlSource() {
         return parseTreeXmlSource;
     }

app/src/main/java/fr/free/nrw/commons/mwapi/UploadResult.java

@@ -9,11 +9,24 @@ public class UploadResult {
     private String imageUrl;
     private String canonicalFilename;
 
+    /**
+     * Minimal constructor
+     *
+     * @param resultStatus Upload result status
+     * @param errorCode    Upload error code
+     */
     UploadResult(String resultStatus, String errorCode) {
         this.resultStatus = resultStatus;
         this.errorCode = errorCode;
     }
 
+    /**
+     * Full-fledged constructor
+     * @param resultStatus Upload result status
+     * @param dateUploaded Uploaded date
+     * @param canonicalFilename Uploaded file name
+     * @param imageUrl Uploaded image file name
+     */
     UploadResult(String resultStatus, Date dateUploaded, String canonicalFilename, String imageUrl) {
         this.resultStatus = resultStatus;
         this.dateUploaded = dateUploaded;
@@ -21,22 +34,42 @@ public class UploadResult {
         this.imageUrl = imageUrl;
     }
 
+    /**
+     * Gets uploaded date
+     * @return Upload date
+     */
     public Date getDateUploaded() {
         return dateUploaded;
     }
 
+    /**
+     * Gets image url
+     * @return Uploaded image url
+     */
     public String getImageUrl() {
         return imageUrl;
     }
 
+    /**
+     * Gets canonical file name
+     * @return Uploaded file name
+     */
     public String getCanonicalFilename() {
         return canonicalFilename;
     }
 
+    /**
+     * Gets upload error code
+     * @return Error code
+     */
     public String getErrorCode() {
         return errorCode;
     }
 
+    /**
+     * Gets upload result status
+     * @return Upload result status
+     */
     public String getResultStatus() {
         return resultStatus;
     }

app/src/main/java/fr/free/nrw/commons/utils/LengthUtils.java

@@ -37,6 +37,13 @@ public class LengthUtils {
         return computeAngleBetween(from, to) * 6371009.0D; // Earth's radius in meter
     }
 
+    /**
+     * Computes angle between two points
+     *
+     * @param from Point A
+     * @param to   Point B
+     * @return Angle in radius
+     */
     private static double computeAngleBetween(LatLng from, LatLng to) {
         return distanceRadians(Math.toRadians(from.getLatitude()),
                 Math.toRadians(from.getLongitude()),
@@ -44,18 +51,43 @@ public class LengthUtils {
                 Math.toRadians(to.getLongitude()));
     }
 
+    /**
+     * Computes arc length between 2 points
+     * @param lat1 Latitude of point A
+     * @param lng1 Longitude of point A
+     * @param lat2 Latitude of point B
+     * @param lng2 Longitude of point B
+     * @return Arc length between the points
+     */
     private static double distanceRadians(double lat1, double lng1, double lat2, double lng2) {
         return arcHav(havDistance(lat1, lat2, lng1 - lng2));
     }
 
+    /**
+     * Computes inverse of haversine
+     * @param x Angle in radian
+     * @return Inverse of haversine
+     */
     private static double arcHav(double x) {
         return 2.0D * Math.asin(Math.sqrt(x));
     }
 
+    /**
+     * Computes distance between two points that are on same Longitude
+     * @param lat1 Latitude of point A
+     * @param lat2 Latitude of point B
+     * @param longitude Longitude on which they lie
+     * @return Arc length between points
+     */
     private static double havDistance(double lat1, double lat2, double longitude) {
         return hav(lat1 - lat2) + hav(longitude) * Math.cos(lat1) * Math.cos(lat2);
     }
 
+    /**
+     * Computes haversine
+     * @param x Angle in radians
+     * @return Haversine of x
+     */
     private static double hav(double x) {
         double sinHalf = Math.sin(x * 0.5D);
         return sinHalf * sinHalf;