Cleaning up documentation

app/src/main/java/acr/browser/lightning/search/suggestions/BaiduSuggestionsModel.java

@@ -12,10 +12,9 @@ import acr.browser.lightning.R;
 import acr.browser.lightning.database.HistoryItem;
 import acr.browser.lightning.utils.FileUtils;
 
-// http://unionsug.baidu.com/su?wd=encodeURIComponent(U)
-// http://suggestion.baidu.com/s?wd=encodeURIComponent(U)&action=opensearch
-
-
+/**
+ * The search suggestions provider for the Baidu search engine.
+ */
 public class BaiduSuggestionsModel extends BaseSuggestionsModel {
 
     @NonNull private static final String ENCODING = "UTF-8";
@@ -28,6 +27,8 @@ public class BaiduSuggestionsModel extends BaseSuggestionsModel {
 
     @NonNull
     protected String createQueryUrl(@NonNull String query, @NonNull String language) {
+        // see http://unionsug.baidu.com/su?wd=encodeURIComponent(U)
+        // see http://suggestion.baidu.com/s?wd=encodeURIComponent(U)&action=opensearch
         return "http://suggestion.baidu.com/s?wd=" + query + "&action=opensearch";
     }
 

app/src/main/java/acr/browser/lightning/search/suggestions/BaseSuggestionsModel.java

@@ -28,6 +28,11 @@ import okhttp3.Request;
 import okhttp3.Response;
 import okhttp3.ResponseBody;
 
+/**
+ * The base search suggestions API. Provides common
+ * fetching and caching functionality for each potential
+ * suggestions provider.
+ */
 public abstract class BaseSuggestionsModel {
 
     private static final String TAG = "BaseSuggestionsModel";
@@ -41,9 +46,23 @@ public abstract class BaseSuggestionsModel {
     @NonNull private final String mEncoding;
     @NonNull private final String mLanguage;
 
+    /**
+     * Create a URL for the given query in the given language.
+     *
+     * @param query    the query that was made.
+     * @param language the locale of the user.
+     * @return should return a URL that can be fetched using a GET.
+     */
     @NonNull
     protected abstract String createQueryUrl(@NonNull String query, @NonNull String language);
 
+    /**
+     * Parse the results of an input stream into a list of {@link HistoryItem}.
+     *
+     * @param inputStream the raw input to parse.
+     * @param results     the list to populate.
+     * @throws Exception throw an exception if anything goes wrong.
+     */
     protected abstract void parseResults(@NonNull InputStream inputStream, @NonNull List<HistoryItem> results) throws Exception;
 
     BaseSuggestionsModel(@NonNull Application application, @NonNull String encoding) {

app/src/main/java/acr/browser/lightning/search/suggestions/DuckSuggestionsModel.java

@@ -13,6 +13,9 @@ import acr.browser.lightning.R;
 import acr.browser.lightning.database.HistoryItem;
 import acr.browser.lightning.utils.FileUtils;
 
+/**
+ * The search suggestions provider for the DuckDuckGo search engine.
+ */
 public final class DuckSuggestionsModel extends BaseSuggestionsModel {
 
     @NonNull private static final String ENCODING = "UTF-8";

app/src/main/java/acr/browser/lightning/search/suggestions/GoogleSuggestionsModel.java

@@ -15,6 +15,9 @@ import java.util.List;
 import acr.browser.lightning.R;
 import acr.browser.lightning.database.HistoryItem;
 
+/**
+ * Search suggestions provider for Google search engine.
+ */
 public class GoogleSuggestionsModel extends BaseSuggestionsModel {
 
     @NonNull private static final String ENCODING = "ISO-8859-1";