Take sentence-level spell checking APIs public

Bug: 6136149

Change-Id: I772164d9c67e95876c228efcce2356a81a06be4f

2 files changed, 30 insertions, 13 deletions

diff --git a/core/java/android/view/textservice/SentenceSuggestionsInfo.java b/core/java/android/view/textservice/SentenceSuggestionsInfo.java
index cb9e496..afd62eb 100644
--- a/core/java/android/view/textservice/SentenceSuggestionsInfo.java
+++ b/core/java/android/view/textservice/SentenceSuggestionsInfo.java
@@ -22,8 +22,13 @@ import android.os.Parcelable;
 import java.util.Arrays;
 
 /**
- * @hide
- * This class contains a metadata of sentence level suggestions from the text service
+ * This class contains a metadata of suggestions returned from a text service
+ * (e.g. {@link android.service.textservice.SpellCheckerService}).
+ * The text service uses this class to return the suggestions
+ * for a sentence. See {@link SuggestionsInfo} which is used for suggestions for a word.
+ * This class extends the functionality of {@link SuggestionsInfo} as far as this class enables
+ * you to put multiple {@link SuggestionsInfo}s on a sentence with the offsets and the lengths
+ * of all {@link SuggestionsInfo}s.
  */
 public final class SentenceSuggestionsInfo implements Parcelable {
 
@@ -82,14 +87,15 @@ public final class SentenceSuggestionsInfo implements Parcelable {
     }
 
     /**
-     * @hide
+     * @return the count of {@link SuggestionsInfo}s this instance holds.
      */
     public int getSuggestionsCount() {
         return mSuggestionsInfos.length;
     }
 
     /**
-     * @hide
+     * @param i the id of {@link SuggestionsInfo}s this instance holds.
+     * @return a {@link SuggestionsInfo} at the specified id
      */
     public SuggestionsInfo getSuggestionsInfoAt(int i) {
         if (i >= 0 && i < mSuggestionsInfos.length) {
@@ -99,7 +105,8 @@ public final class SentenceSuggestionsInfo implements Parcelable {
     }
 
     /**
-     * @hide
+     * @param i the id of {@link SuggestionsInfo}s this instance holds
+     * @return the offset of the specified {@link SuggestionsInfo}
      */
     public int getOffsetAt(int i) {
         if (i >= 0 && i < mOffsets.length) {
@@ -109,7 +116,8 @@ public final class SentenceSuggestionsInfo implements Parcelable {
     }
 
     /**
-     * @hide
+     * @param i the id of {@link SuggestionsInfo}s this instance holds
+     * @return the length of the specified {@link SuggestionsInfo}
      */
     public int getLengthAt(int i) {
         if (i >= 0 && i < mLengths.length) {
diff --git a/core/java/android/view/textservice/SpellCheckerSession.java b/core/java/android/view/textservice/SpellCheckerSession.java
index 6ff3b9b..35940ba 100644
--- a/core/java/android/view/textservice/SpellCheckerSession.java
+++ b/core/java/android/view/textservice/SpellCheckerSession.java
@@ -178,17 +178,19 @@ public class SpellCheckerSession {
     }
 
     /**
-     * @hide
+     * Get suggestions from the specified sentences
+     * @param textInfos an array of text metadata for a spell checker
+     * @param suggestionsLimit the maximum number of suggestions that will be returned
      */
-    public void getSentenceSuggestions(TextInfo[] textInfo, int suggestionsLimit) {
+    public void getSentenceSuggestions(TextInfo[] textInfos, int suggestionsLimit) {
         mSpellCheckerSessionListenerImpl.getSentenceSuggestionsMultiple(
-                textInfo, suggestionsLimit);
+                textInfos, suggestionsLimit);
     }
 
     /**
      * Get candidate strings for a substring of the specified text.
      * @param textInfo text metadata for a spell checker
-     * @param suggestionsLimit the number of limit of suggestions returned
+     * @param suggestionsLimit the maximum number of suggestions that will be returned
      */
     public void getSuggestions(TextInfo textInfo, int suggestionsLimit) {
         getSuggestions(new TextInfo[] {textInfo}, suggestionsLimit, false);
@@ -197,7 +199,7 @@ public class SpellCheckerSession {
     /**
      * A batch process of getSuggestions
      * @param textInfos an array of text metadata for a spell checker
-     * @param suggestionsLimit the number of limit of suggestions returned
+     * @param suggestionsLimit the maximum number of suggestions that will be returned
      * @param sequentialWords true if textInfos can be treated as sequential words.
      */
     public void getSuggestions(
@@ -434,12 +436,19 @@ public class SpellCheckerSession {
      */
     public interface SpellCheckerSessionListener {
         /**
-         * Callback for "getSuggestions"
-         * @param results an array of results of getSuggestions
+         * Callback for {@link SpellCheckerSession#getSuggestions(TextInfo[], int, boolean)}
+         * @param results an array of {@link SuggestionsInfo}s.
+         * These results are suggestions for {@link TextInfo}s queried by
+         * {@link SpellCheckerSession#getSuggestions(TextInfo[], int, boolean)}.
          */
         public void onGetSuggestions(SuggestionsInfo[] results);
+        // TODO: Remove @hide as soon as the sample spell checker client gets fixed.
         /**
          * @hide
+         * Callback for {@link SpellCheckerSession#getSentenceSuggestions(TextInfo[], int)}
+         * @param results an array of {@link SentenceSuggestionsInfo}s.
+         * These results are suggestions for {@link TextInfo}s
+         * queried by {@link SpellCheckerSession#getSentenceSuggestions(TextInfo[], int)}.
          */
         public void onGetSentenceSuggestions(SentenceSuggestionsInfo[] results);
     }