From 519afe3f4707e496fce47954f1aca000e4270046 Mon Sep 17 00:00:00 2001
From: misaochan <josephinelim86@gmail.com>
Date: Fri, 21 Oct 2016 18:09:45 +1300
Subject: [PATCH] Add comments

---
 .../commons/category/CategorizationFragment.java   | 14 +++++++++-----
 .../free/nrw/commons/category/TitleCategories.java |  6 +++++-
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/app/src/main/java/fr/free/nrw/commons/category/CategorizationFragment.java b/app/src/main/java/fr/free/nrw/commons/category/CategorizationFragment.java
index a0dae932c..b28c1a04b 100644
--- a/app/src/main/java/fr/free/nrw/commons/category/CategorizationFragment.java
+++ b/app/src/main/java/fr/free/nrw/commons/category/CategorizationFragment.java
@@ -121,8 +121,10 @@ public class CategorizationFragment extends Fragment {
         }
     }
 
-    //TODO: Probably add 'suggest from filename' cats here. We want it to be displayed at start, not upon typing
-    //TODO: Search using MethodA query, but can't use MethodAUpdater because we don't want it updating when user types
+    /**
+     * Retrieves category suggestions from title input
+     * @return a list containing title-related categories
+     */
     protected ArrayList<String> titleCatQuery() {
 
         TitleCategories titleCategoriesSub;
@@ -132,6 +134,7 @@ public class CategorizationFragment extends Fragment {
         String title = titleDesc.getString("Title", "");
         Log.d(TAG, "Title: " + title);
 
+        //Override onPostExecute to access the results of async API call
         titleCategoriesSub = new TitleCategories(title) {
             @Override
             protected void onPostExecute(ArrayList<String> result) {
@@ -142,8 +145,11 @@ public class CategorizationFragment extends Fragment {
                 mergeLatch.countDown();
             }
         };
+
         titleCategoriesSub.execute();
         Log.d(TAG, "TitleCatItems in titleCatQuery: " + titleCatItems);
+
+        //Only return titleCatItems after API call has finished
         try {
             mergeLatch.await();
         } catch (InterruptedException e) {
@@ -152,15 +158,13 @@ public class CategorizationFragment extends Fragment {
         return titleCatItems;
     }
 
-
-
     /**
      * Retrieves recently-used categories
      * @return a list containing recent categories
      */
     protected ArrayList<String> recentCatQuery() {
         ArrayList<String> items = new ArrayList<String>();
-        
+
         try {
             Cursor cursor = client.query(
                     CategoryContentProvider.BASE_URI,
diff --git a/app/src/main/java/fr/free/nrw/commons/category/TitleCategories.java b/app/src/main/java/fr/free/nrw/commons/category/TitleCategories.java
index 954a1c6c0..7d5a7607e 100644
--- a/app/src/main/java/fr/free/nrw/commons/category/TitleCategories.java
+++ b/app/src/main/java/fr/free/nrw/commons/category/TitleCategories.java
@@ -13,7 +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 related to
+ * the title entered in previous screen. The 'srsearch' action-specific parameter is used for this
+ * purpose. This class should be subclassed in CategorizationFragment.java to add the results to recent and GPS cats.
+ */
 public class TitleCategories extends AsyncTask<Void, Void, ArrayList<String>> {
 
     private final static int SEARCH_CATS_LIMIT = 25;