Take sentence-level spell checking APIs public

Bug: 6136149

Change-Id: I772164d9c67e95876c228efcce2356a81a06be4f

api/current.txt

@@ -18916,6 +18916,7 @@ package android.service.textservice {
     method public void onCancel();
     method public void onClose();
     method public abstract void onCreate();
+    method public android.view.textservice.SentenceSuggestionsInfo[] onGetSentenceSuggestionsMultiple(android.view.textservice.TextInfo[], int);
     method public abstract android.view.textservice.SuggestionsInfo onGetSuggestions(android.view.textservice.TextInfo, int);
     method public android.view.textservice.SuggestionsInfo[] onGetSuggestionsMultiple(android.view.textservice.TextInfo[], int, boolean);
   }
@@ -25147,6 +25148,18 @@ package android.view.inputmethod {
 
 package android.view.textservice {
 
+  public final class SentenceSuggestionsInfo implements android.os.Parcelable {
+    ctor public SentenceSuggestionsInfo(android.view.textservice.SuggestionsInfo[], int[], int[]);
+    ctor public SentenceSuggestionsInfo(android.os.Parcel);
+    method public int describeContents();
+    method public int getLengthAt(int);
+    method public int getOffsetAt(int);
+    method public int getSuggestionsCount();
+    method public android.view.textservice.SuggestionsInfo getSuggestionsInfoAt(int);
+    method public void writeToParcel(android.os.Parcel, int);
+    field public static final android.os.Parcelable.Creator CREATOR;
+  }
+
   public final class SpellCheckerInfo implements android.os.Parcelable {
     method public int describeContents();
     method public android.content.ComponentName getComponent();
@@ -25165,6 +25178,7 @@ package android.view.textservice {
   public class SpellCheckerSession {
     method public void cancel();
     method public void close();
+    method public void getSentenceSuggestions(android.view.textservice.TextInfo[], int);
     method public android.view.textservice.SpellCheckerInfo getSpellChecker();
     method public void getSuggestions(android.view.textservice.TextInfo, int);
     method public void getSuggestions(android.view.textservice.TextInfo[], int, boolean);

core/java/android/service/textservice/SpellCheckerService.java

@@ -112,7 +112,7 @@ public abstract class SpellCheckerService extends Service {
          * So, this is not called on the main thread,
          * but will be called in series on another thread.
          * @param textInfo the text metadata
-         * @param suggestionsLimit the number of limit of suggestions returned
+         * @param suggestionsLimit the maximum number of suggestions to be returned
          * @return SuggestionsInfo which contains suggestions for textInfo
          */
         public abstract SuggestionsInfo onGetSuggestions(TextInfo textInfo, int suggestionsLimit);
@@ -123,9 +123,10 @@ public abstract class SpellCheckerService extends Service {
          * So, this is not called on the main thread,
          * but will be called in series on another thread.
          * @param textInfos an array of the text metadata
-         * @param suggestionsLimit the number of limit of suggestions returned
+         * @param suggestionsLimit the maximum number of suggestions to be returned
          * @param sequentialWords true if textInfos can be treated as sequential words.
-         * @return an array of SuggestionsInfo of onGetSuggestions
+         * @return an array of {@link SentenceSuggestionsInfo} returned by
+         * {@link SpellCheckerService.Session#onGetSuggestions(TextInfo, int)}
          */
         public SuggestionsInfo[] onGetSuggestionsMultiple(TextInfo[] textInfos,
                 int suggestionsLimit, boolean sequentialWords) {
@@ -140,11 +141,14 @@ public abstract class SpellCheckerService extends Service {
         }
 
         /**
-         * @hide
          * The default implementation returns an array of SentenceSuggestionsInfo by simply calling
          * onGetSuggestions().
          * When you override this method, make sure that suggestionsLimit is applied to suggestions
          * that share the same start position and length.
+         * @param textInfos an array of the text metadata
+         * @param suggestionsLimit the maximum number of suggestions to be returned
+         * @return an array of {@link SentenceSuggestionsInfo} returned by
+         * {@link SpellCheckerService.Session#onGetSuggestions(TextInfo, int)}
          */
         public SentenceSuggestionsInfo[] onGetSentenceSuggestionsMultiple(TextInfo[] textInfos,
                 int suggestionsLimit) {

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) {

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);
     }