Merge pull request #71 from misaochan/master

Added Javadocs

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Wikimedia Commons for Android
 
+## v1.12
+- Further bug fixes for Polish language
+- Added Javadocs
+
 ## v1.11
 - Bugfix for Polish language crash
 

commons/AndroidManifest.xml

@@ -1,7 +1,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="fr.free.nrw.commons"
-    android:versionCode="27"
-    android:versionName="1.11" >
+    android:versionCode="28"
+    android:versionName="1.12" >
 
     <uses-sdk
         android:minSdkVersion="9"

commons/src/main/java/fr/free/nrw/commons/category/CategorizationFragment.java

@@ -33,7 +33,9 @@ import java.util.Set;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.ScheduledThreadPoolExecutor;
 
-
+/**
+ * Displays the category suggestion and selection screen. Category search is initiated here.
+ */
 public class CategorizationFragment extends SherlockFragment{
     public static interface OnCategoriesSaveHandler {
         public void onCategoriesSave(ArrayList<String> categories);
@@ -96,6 +98,10 @@ public class CategorizationFragment extends SherlockFragment{
         }
     }
 
+    /**
+     * Retrieves recently-used categories and nearby categories, and merges them without duplicates.
+     * @return a list containing these categories
+     */
     protected ArrayList<String> recentCatQuery() {
         ArrayList<String> items = new ArrayList<String>();
         Set<String> mergedItems = new LinkedHashSet<String>();
@@ -133,7 +139,11 @@ public class CategorizationFragment extends SherlockFragment{
         return mergedItemsList;
     }
 
-
+    /**
+     * Displays categories found to the user as they type in the search box
+     * @param categories a list of all categories found for the search string
+     * @param filter the search string
+     */
     protected void setCatsAfterAsync(ArrayList<String> categories, String filter) {
 
         if (getActivity() != null) {
@@ -338,6 +348,12 @@ public class CategorizationFragment extends SherlockFragment{
         return rootView;
     }
 
+    /**
+     * Makes asynchronous calls to the Commons MediaWiki API via anonymous subclasses of
+     * 'MethodAUpdater' and 'PrefixUpdater'. Some of their methods are overridden in order to
+     * aggregate the results. A CountDownLatch is used to ensure that MethodA results are shown
+     * above Prefix results.
+     */
     private void requestSearchResults() {
 
         final CountDownLatch latch = new CountDownLatch(1);

commons/src/main/java/fr/free/nrw/commons/category/MethodAUpdater.java

@@ -1,6 +1,5 @@
 package fr.free.nrw.commons.category;
 
-
 import android.os.AsyncTask;
 import android.text.TextUtils;
 import android.util.Log;
@@ -14,6 +13,11 @@ import java.util.ArrayList;
 
 import fr.free.nrw.commons.CommonsApplication;
 
+/**
+ * Sends asynchronous queries to the Commons MediaWiki API to retrieve categories that are close to
+ * the keyword typed in by the user. The 'srsearch' action-specific parameter is used for this
+ * purpose. This class should be subclassed in CategorizationFragment.java to aggregate the results.
+ */
 public class MethodAUpdater extends AsyncTask<Void, Void, ArrayList<String>> {
 
     private String filter;

commons/src/main/java/fr/free/nrw/commons/category/PrefixUpdater.java

@@ -13,6 +13,12 @@ import java.util.ArrayList;
 
 import fr.free.nrw.commons.CommonsApplication;
 
+/**
+ * Sends asynchronous queries to the Commons MediaWiki API to retrieve categories that share the
+ * same prefix as the keyword typed in by the user. The 'acprefix' action-specific parameter is used
+ * for this purpose. This class should be subclassed in CategorizationFragment.java to aggregate
+ * the results.
+ */
 public class PrefixUpdater extends AsyncTask<Void, Void, ArrayList<String>> {
 
     private String filter;

commons/src/main/java/fr/free/nrw/commons/upload/GPSExtractor.java

@@ -12,6 +12,11 @@ import android.preference.PreferenceManager;
 import android.util.Log;
 import java.io.IOException;
 
+/**
+ * Extracts geolocation to be passed to API for category suggestions. If a picture with geolocation
+ * is uploaded, extract latitude and longitude from EXIF data of image. If a picture without
+ * geolocation is uploaded, retrieve user's location (if enabled in Settings).
+ */
 public class GPSExtractor {
 
     private static final String TAG = GPSExtractor.class.getName();
@@ -31,6 +36,10 @@ public class GPSExtractor {
         this.context = context;
     }
 
+    /**
+     * Check if user enabled retrieval of their current location in Settings
+     * @return true if enabled, false if disabled
+     */
     private boolean gpsPreferenceEnabled() {
         SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(context);
         boolean gpsPref = sharedPref.getBoolean("allowGps", false);
@@ -38,6 +47,9 @@ public class GPSExtractor {
         return gpsPref;
     }
 
+    /**
+     * Registers a LocationManager to listen for current location
+     */
     protected void registerLocationManager() {
         locationManager = (LocationManager) context.getSystemService(Context.LOCATION_SERVICE);
         criteria = new Criteria();
@@ -55,7 +67,10 @@ public class GPSExtractor {
         locationManager.removeUpdates(myLocationListener);
     }
 
-    //Extract GPS coords of image
+    /**
+     * Extracts geolocation of image from EXIF data.
+     * @return coordinates of image as string (needs to be passed as a String in API query)
+     */
     public String getCoords() {
 
         ExifInterface exif;
@@ -136,7 +151,10 @@ public class GPSExtractor {
         return decLongitude;
     }
 
-    //Converts format of coords into decimal coords as required by MediaWiki API
+    /**
+     * Converts format of geolocation into decimal coordinates as required by MediaWiki API
+     * @return the coordinates in decimals
+     */
     private String getDecimalCoords(String latitude, String latitude_ref, String longitude, String longitude_ref) {
 
         if (latitude_ref.equals("N")) {

commons/src/main/java/fr/free/nrw/commons/upload/MwVolleyApi.java

@@ -17,15 +17,17 @@ import com.android.volley.toolbox.Volley;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 
-
 import java.io.UnsupportedEncodingException;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
-import fr.free.nrw.commons.caching.CacheController;
-
+/**
+ * Uses the Volley library to implement asynchronous calls to the Commons MediaWiki API to match
+ * GPS coordinates with nearby Commons categories. Parses the results using GSON to obtain a list
+ * of relevant categories.
+ */
 public class MwVolleyApi {
 
     private static RequestQueue REQUEST_QUEUE;
@@ -66,8 +68,9 @@ public class MwVolleyApi {
 
     /**
      * Builds URL with image coords for MediaWiki API calls
-     * Example URL: https://commons.wikimedia.org/w/api.php?action=query&prop=categories|coordinates|pageprops&format=json&clshow=!hidden&coprop=type|name|dim|country|region|globe&codistancefrompoint=38.11386944444445|13.356263888888888&
-     * generator=geosearch&redirects=&ggscoord=38.11386944444445|13.356263888888888&ggsradius=100&ggslimit=10&ggsnamespace=6&ggsprop=type|name|dim|country|region|globe&ggsprimary=all&formatversion=2
+     * Example URL: https://commons.wikimedia.org/w/api.php?action=query&prop=categories|coordinates|pageprops&format=json&clshow=!hidden&coprop=type|name|dim|country|region|globe&codistancefrompoint=38.11386944444445|13.356263888888888&generator=geosearch&redirects=&ggscoord=38.11386944444445|1.356263888888888&ggsradius=100&ggslimit=10&ggsnamespace=6&ggsprop=type|name|dim|country|region|globe&ggsprimary=all&formatversion=2
+     * @param coords Coordinates to build query with
+     * @return URL for API query
      */
     private String buildUrl (String coords){
 
@@ -134,7 +137,6 @@ public class MwVolleyApi {
         @Override
         protected Response<QueryResponse> parseNetworkResponse(NetworkResponse response) {
             String json = parseString(response);
-            //Log.d(TAG, "json=" + json);
             QueryResponse queryResponse = GSON.fromJson(json, QueryResponse.class);
             return Response.success(queryResponse, cacheEntry(response));
         }

commons/src/main/java/fr/free/nrw/commons/upload/ShareActivity.java

@@ -27,8 +27,10 @@ import fr.free.nrw.commons.modifications.ModifierSequence;
 import java.util.ArrayList;
 import java.util.List;
 
-
-
+/**
+ * Activity for the title/desc screen after image is selected. Also starts processing image
+ * GPS coordinates or user location (if enabled in Settings) for category suggestions.
+ */
 public  class       ShareActivity
         extends     AuthenticatedActivity
         implements  SingleUploadFragment.OnUploadActionInitiated,
@@ -195,6 +197,10 @@ public  class       ShareActivity
         requestAuthToken();
     }
 
+    /**
+     * Initiates retrieval of image coordinates or user coordinates, and caching of coordinates.
+     * Then initiates the calls to MediaWiki API through an instance of MwVolleyApi.
+     */
     @Override
     public void onResume() {
         super.onResume();