Merge pull request commons-app#1025 from prajgov/master

Added JavaDoc comments to few methods and classes

Author: nicolas-raoul

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

@@ -8,10 +8,18 @@
 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

@@ -49,16 +49,21 @@ public class CommonsApplication extends DaggerApplication {
     @Inject @Named("default_preferences") SharedPreferences defaultPrefs;
     @Inject @Named("application_preferences") SharedPreferences applicationPrefs;
     @Inject @Named("prefs") SharedPreferences otherPrefs;
-
+    
     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,23 +85,41 @@ public void onCreate() {
         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;
         }
         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 CommonsApplicationComponent injector() {
         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 @@ private void updateAllDatabases() {
         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 @@
 
 import android.support.annotation.Nullable;
 
+/**
+ * represents Licence object
+ */
 public class License {
     private String key;
     private String template;
@@ -56,6 +59,12 @@ public String getName() {
         }
     }
 
+    /**
+     * 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.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 LicenseList(Activity activity) {
         }
     }
 
+    /**
+     * 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,13 +72,23 @@ License licenseForTemplate(String template) {
         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
         return "license_name_" + template.toLowerCase(Locale.ENGLISH).replace("-",
                 "_").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);
@@ -92,4 +124,4 @@ private boolean xmlFastForward(XmlPullParser parser, String namespace, String el
         }
     }
 
-}
+}

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

@@ -47,16 +47,35 @@ public Media[] newArray(int i) {
     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 Media(Parcel in) {
         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 String getDisplayTitle() {
         }
     }
 
+    /**
+     * 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 void setCategories(List<String> categories) {
         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 @@ void setDescriptions(Map<String, String> descriptions) {
         }
     }
 
+    /**
+     * 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 String getDescription(String preferredLanguage) {
         }
     }
 
+    /**
+     * 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);