update comments and documentation

currently irrelevant changes to dump methods

app/src/main/java/helium314/keyboard/latin/DictionaryFacilitator.java

@@ -42,14 +42,10 @@ public interface DictionaryFacilitator {
             Dictionary.TYPE_USER_HISTORY,
             Dictionary.TYPE_USER};
 
-    /**
+    /** The facilitator will put words into the cache whenever it decodes them. */
-     * The facilitator will put words into the cache whenever it decodes them.
-     */
     void setValidSpellingWordReadCache(final LruCache<String, Boolean> cache);
 
-    /**
+    /** The facilitator will get words from the cache whenever it needs to check their spelling. */
-     * The facilitator will get words from the cache whenever it needs to check their spelling.
-     */
     void setValidSpellingWordWriteCache(final LruCache<String, Boolean> cache);
 
     /**
@@ -79,12 +75,14 @@ public interface DictionaryFacilitator {
      */
     void onFinishInput(Context context);
 
+    /** whether a dictionary is set */
     boolean isActive();
 
+    /** the locale provided in resetDictionaries */
     @NonNull Locale getMainLocale();
 
-    // useful for multilingual typing
+    /** the most "trusted" locale, differs from getMainLocale only if multilingual typing is used */
-    Locale getCurrentLocale();
+    @NonNull Locale getCurrentLocale();
 
     boolean usesSameSettings(
             @NonNull final List<Locale> locales,
@@ -93,6 +91,7 @@ public interface DictionaryFacilitator {
             final boolean personalization
     );
 
+    /** switches to newLocale, gets secondary locales from current settings, and sets secondary dictionaries */
     void resetDictionaries(
             final Context context,
             final Locale newLocale,
@@ -103,30 +102,37 @@ public interface DictionaryFacilitator {
             final String dictNamePrefix,
             @Nullable final DictionaryInitializationListener listener);
 
+    /** removes the word from all editable dictionaries, and adds it to a blacklist in case it's in a read-only dictionary */
     void removeWord(String word);
 
     void closeDictionaries();
 
-    // The main dictionaries are loaded asynchronously. Don't cache the return value
+    /** main dictionaries are loaded asynchronously after resetDictionaries */
-    // of these methods.
     boolean hasAtLeastOneInitializedMainDictionary();
 
+    /** main dictionaries are loaded asynchronously after resetDictionaries */
     boolean hasAtLeastOneUninitializedMainDictionary();
 
+    /** main dictionaries are loaded asynchronously after resetDictionaries */
     void waitForLoadingMainDictionaries(final long timeout, final TimeUnit unit)
             throws InterruptedException;
 
+    /** adds the word to user history dictionary, calls adjustConfindences, and might add it to personal dictionary if the setting is enabled */
     void addToUserHistory(final String suggestion, final boolean wasAutoCapitalized,
             @NonNull final NgramContext ngramContext, final long timeStampInSeconds,
             final boolean blockPotentiallyOffensive);
 
+    /** adjust confidences for multilingual typing */
     void adjustConfidences(final String word, final boolean wasAutoCapitalized);
 
+    /** a string with all used locales and their current confidences, null if multilingual typing is not used */
+    @Nullable String localesAndConfidences();
+
+    /** completely removes the word from user history (currently not if event is a backspace event) */
     void unlearnFromUserHistory(final String word,
             @NonNull final NgramContext ngramContext, final long timeStampInSeconds,
             final int eventType);
 
-    // TODO: Revise the way to fusion suggestion results.
     @NonNull SuggestionResults getSuggestionResults(final ComposedData composedData,
             final NgramContext ngramContext, @NonNull final Keyboard keyboard,
             final SettingsValuesForSuggestion settingsValuesForSuggestion, final int sessionId,
@@ -136,12 +142,10 @@ public interface DictionaryFacilitator {
 
     boolean isValidSuggestionWord(final String word);
 
-    boolean clearUserHistoryDictionary(final Context context);
+    void clearUserHistoryDictionary(final Context context);
 
     String dump(final Context context);
 
-    String localesAndConfidences();
-
     void dumpDictionaryForDebug(final String dictName);
 
     @NonNull List<DictionaryStats> getDictionaryStats(final Context context);

app/src/main/java/helium314/keyboard/latin/DictionaryFacilitatorImpl.kt

@@ -212,7 +212,7 @@ class DictionaryFacilitatorImpl : DictionaryFacilitator {
                     || !oldDictGroupForLocale.hasDict(subDictType)
                 ) {
                     // Create a new dictionary.
-                    subDict = getSubDict(subDictType, context, locale, null, dictNamePrefix) ?: continue
+                    subDict = createSubDict(subDictType, context, locale, null, dictNamePrefix) ?: continue
                 } else {
                     // Reuse the existing dictionary.
                     subDict = oldDictGroupForLocale.getSubDict(subDictType) ?: continue
@@ -556,14 +556,10 @@ class DictionaryFacilitatorImpl : DictionaryFacilitator {
         }
     }
 
-    // todo: remove return value, not used
+    override fun clearUserHistoryDictionary(context: Context) {
-    override fun clearUserHistoryDictionary(context: Context): Boolean {
         for (dictionaryGroup in dictionaryGroups) {
-            val dictionary = dictionaryGroup.getSubDict(Dictionary.TYPE_USER_HISTORY)
+            dictionaryGroup.getSubDict(Dictionary.TYPE_USER_HISTORY)?.clear()
-                ?: return false
-            dictionary.clear()
         }
-        return true
     }
 
     override fun localesAndConfidences(): String? {
@@ -581,12 +577,11 @@ class DictionaryFacilitatorImpl : DictionaryFacilitator {
     }
 
     override fun getDictionaryStats(context: Context): List<DictionaryStats> =
-        DictionaryFacilitator.DYNAMIC_DICTIONARY_TYPES.mapNotNull {
+        DictionaryFacilitator.DYNAMIC_DICTIONARY_TYPES.flatMap { dictType ->
-            dictionaryGroups[0].getSubDict(it)?.dictionaryStats
+            dictionaryGroups.mapNotNull { it.getSubDict(dictType)?.dictionaryStats }
         }
 
-    // todo: remove from interface?
+    override fun dump(context: Context) = getDictionaryStats(context).joinToString("\n")
-    override fun dump(context: Context) = ""
 
     companion object {
         private val TAG = DictionaryFacilitatorImpl::class.java.simpleName
@@ -594,7 +589,7 @@ class DictionaryFacilitatorImpl : DictionaryFacilitator {
         // HACK: This threshold is being used when adding a capitalized entry in the User History dictionary.
         private const val CAPITALIZED_FORM_MAX_PROBABILITY_FOR_INSERT = 140
 
-        private fun getSubDict(
+        private fun createSubDict(
             dictType: String, context: Context, locale: Locale, dictFile: File?, dictNamePrefix: String
         ): ExpandableBinaryDictionary? {
             try {