From 33c75c63ac204869aeb18f5f64f4c96069b1bb85 Mon Sep 17 00:00:00 2001
From: Lan Wei <azurewei@google.com>
Date: Fri, 30 Oct 2020 12:56:42 +0800
Subject: [PATCH] API review: Update javadoc for
 InputConnection#getSurroudingText

Update java doc about the selection range and flags.

Test: only updates javadoc, no logic changes. Existing unit tests still pass.

BUG=171804584

Change-Id: Ife314031d728cf4c9d3512110acb3ae985572e7d
---
 .../android/view/inputmethod/InputConnection.java | 15 ++++++++-------
 .../android/view/inputmethod/SurroundingText.java |  8 ++++++++
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index 0fe47b7828d92..14b5d7c72d2f8 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -190,7 +190,7 @@ public interface InputConnection {
      *
      * @param n The expected length of the text. This must be non-negative.
      * @param flags Supplies additional options controlling how the text is
-     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
+     * returned. May be either {@code 0} or {@link #GET_TEXT_WITH_STYLES}.
      * @return the text before the cursor position; the length of the
      * returned text might be less than <var>n</var>.
      * @throws IllegalArgumentException if {@code n} is negative.
@@ -234,7 +234,7 @@ public interface InputConnection {
      *
      * @param n The expected length of the text. This must be non-negative.
      * @param flags Supplies additional options controlling how the text is
-     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
+     * returned. May be either {@code 0} or {@link #GET_TEXT_WITH_STYLES}.
      *
      * @return the text after the cursor position; the length of the
      * returned text might be less than <var>n</var>.
@@ -273,7 +273,7 @@ public interface InputConnection {
      * consistent with the results of the latest edits.</p>
      *
      * @param flags Supplies additional options controlling how the text is
-     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
+     * returned. May be either {@code 0} or {@link #GET_TEXT_WITH_STYLES}.
      * @return the text that is currently selected, if any, or null if
      * no text is selected. In {@link android.os.Build.VERSION_CODES#N} and
      * later, returns false when the target application does not implement
@@ -284,7 +284,8 @@ public interface InputConnection {
     /**
      * Gets the surrounding text around the current cursor, with <var>beforeLength</var> characters
      * of text before the cursor (start of the selection), <var>afterLength</var> characters of text
-     * after the cursor (end of the selection), and all of the selected text.
+     * after the cursor (end of the selection), and all of the selected text. The range are for java
+     * characters, not glyphs that can be multiple characters.
      *
      * <p>This method may fail either if the input connection has become invalid (such as its
      * process crashing), or the client is taking too long to respond with the text (it is given a
@@ -306,8 +307,8 @@ public interface InputConnection {
      *
      * @param beforeLength The expected length of the text before the cursor.
      * @param afterLength The expected length of the text after the cursor.
-     * @param flags Supplies additional options controlling how the text is returned. Defined by the
-     *              constants.
+     * @param flags Supplies additional options controlling how the text is returned. May be either
+     *              {@code 0} or {@link #GET_TEXT_WITH_STYLES}.
      * @return an {@link android.view.inputmethod.SurroundingText} object describing the surrounding
      * text and state of selection, or null if the input connection is no longer valid, or the
      * editor can't comply with the request for some reason, or the application does not implement
@@ -394,7 +395,7 @@ public interface InputConnection {
      *
      * @param request Description of how the text should be returned.
      * {@link android.view.inputmethod.ExtractedTextRequest}
-     * @param flags Additional options to control the client, either 0 or
+     * @param flags Additional options to control the client, either {@code 0} or
      * {@link #GET_EXTRACTED_TEXT_MONITOR}.
 
      * @return an {@link android.view.inputmethod.ExtractedText}
diff --git a/core/java/android/view/inputmethod/SurroundingText.java b/core/java/android/view/inputmethod/SurroundingText.java
index 506f95a4ac7bc..94e05a830b850 100644
--- a/core/java/android/view/inputmethod/SurroundingText.java
+++ b/core/java/android/view/inputmethod/SurroundingText.java
@@ -90,6 +90,10 @@ public final class SurroundingText implements Parcelable {
 
     /**
      * Returns the text offset of the start of the selection in the surrounding text.
+     *
+     * <p>A selection is the current range of the text that is selected by the user, or the current
+     * position of the cursor. A cursor is a selection where the start and end are at the same
+     * offset.<p>
      */
     @IntRange(from = 0)
     public int getSelectionStart() {
@@ -98,6 +102,10 @@ public final class SurroundingText implements Parcelable {
 
     /**
      * Returns the text offset of the end of the selection in the surrounding text.
+     *
+     * <p>A selection is the current range of the text that is selected by the user, or the current
+     * position of the cursor. A cursor is a selection where the start and end are at the same
+     * offset.<p>
      */
     @IntRange(from = 0)
     public int getSelectionEnd() {