Update comments

Author: bleroux

shell/platform/android/io/flutter/embedding/engine/systemchannels/ProcessTextChannel.java

@@ -18,20 +18,21 @@
  * {@link ProcessTextChannel} is a platform channel that is used by the framework to initiate text
  * processing feature in the embedding and for the embedding to send back the results.
  *
- * <p>When there is new a text context menu to display, the framework will send to the embedding the
- * message {@code ProcessText.queryTextActions}. In response, the {@link
- * io.flutter.plugin.text.ProcessTextPlugin} will return a map of all activities that can be
- * performed to process text. The map keys are generated IDs and the values are the activities
- * labels. On the first request, the {@link io.flutter.plugin.text.ProcessTextPlugin} will make a
- * call to Android's package manager to query all activities that can be performed for the {@code
- * Intent.ACTION_PROCESS_TEXT} intent.
+ * <p>When the framework needs to query the list of text processing actions (for instance to expose
+ * them in the selected text context menu), it will send to the embedding the message {@code
+ * ProcessText.queryTextActions}. In response, the {@link io.flutter.plugin.text.ProcessTextPlugin}
+ * will return a map of all activities that can process text. The map keys are generated IDs and the
+ * values are the activities labels. On the first request, the {@link
+ * io.flutter.plugin.text.ProcessTextPlugin} will make a call to Android's package manager to query
+ * all activities that can be performed for the {@code Intent.ACTION_PROCESS_TEXT} intent.
  *
- * <p>When an text processing action has to be executed, the framework will send to the embedding
- * the message {@code ProcessText.processTextAction} with the {@code int id} of the choosen text
- * action and the {@code String} of text to process as arguments. In response, the {@link
+ * <p>When a text processing action has to be executed, the framework will send to the embedding the
+ * message {@code ProcessText.processTextAction} with the {@code int id} of the choosen text action
+ * and the {@code String} of text to process as arguments. In response, the {@link
  * io.flutter.plugin.text.ProcessTextPlugin} will make a call to the Android application activity to
- * start the activity exposing the text action and it will return the processed text, or null if the
- * activity did not return a value.
+ * start the activity exposing the text action. The {@link io.flutter.plugin.text.ProcessTextPlugin}
+ * will return the processed text if there is one, or null if the activity did not return a
+ * transformed text.
  *
  * <p>{@link io.flutter.plugin.text.ProcessTextPlugin} implements {@link ProcessTextMethodHandler}
  * that parses incoming messages from Flutter.
@@ -99,15 +100,13 @@ public void setMethodHandler(@Nullable ProcessTextMethodHandler processTextMetho
   }
 
   public interface ProcessTextMethodHandler {
-    /**
-     * Requests the list of text actions. Each text action has a unique id and a localized label.
-     */
+    /** Requests the map of text actions. Each text action has a unique id and a localized label. */
     Map<Integer, String> queryTextActions();
 
     /**
      * Requests to run a text action on a given input text.
      *
-     * @param id The ID of the text action returned by queryTextActions.
+     * @param id The ID of the text action returned by {@code ProcessText.queryTextActions}.
      * @param input The text to be processed.
      * @param readOnly Indicates to the activity if the processed text will be used as read-only.
      *     see

shell/platform/android/io/flutter/plugin/text/ProcessTextPlugin.java

@@ -97,8 +97,8 @@ public void processTextAction(
     intent.putExtra(Intent.EXTRA_PROCESS_TEXT, text);
     intent.putExtra(Intent.EXTRA_PROCESS_TEXT_READONLY, readOnly);
 
-    // Start the text processing activity. onActivityResult callback is called
-    // when the activity completes.
+    // Start the text processing activity. When the activity complets, the onActivityResult callback
+    // is called.
     activityBinding.getActivity().startActivityForResult(intent, requestCode);
   }
 
@@ -128,7 +128,11 @@ private void cacheResolveInfos() {
   /**
    * Executed when a text processing activity terminates.
    *
-   * <p>The result is null when an activity does not return an updated text.
+   * <p>When an activity returns a value, the request is completed successfully and returns the
+   * processed text.
+   *
+   * <p>When an activity does not return a valuen. the request is completed successfully and returns
+   * null.
    */
   @TargetApi(Build.VERSION_CODES.M)
   @RequiresApi(Build.VERSION_CODES.M)

shell/platform/android/test/io/flutter/plugin/text/ProcessTextPluginTest.java

@@ -126,13 +126,13 @@ public void performProcessTextActionWithNoReturnedValue() {
     final int action2Id = 1;
     assertEquals(textActions, Map.of(action1Id, "Action1", action2Id, "Action2"));
 
-    // Set up activity binding.
+    // Set up the activity binding.
     ActivityPluginBinding mockActivityPluginBinding = mock(ActivityPluginBinding.class);
     Activity mockActivity = mock(Activity.class);
     when(mockActivityPluginBinding.getActivity()).thenReturn(mockActivity);
     processTextPlugin.onAttachedToActivity(mockActivityPluginBinding);
 
-    // Execute first action.
+    // Execute th first action.
     String textToBeProcessed = "Flutter!";
     MethodChannel.Result result = mock(MethodChannel.Result.class);
     processTextPlugin.processTextAction(action1Id, textToBeProcessed, false, result);
@@ -143,7 +143,7 @@ public void performProcessTextActionWithNoReturnedValue() {
     Intent intent = intentCaptor.getValue();
     assertEquals(intent.getStringExtra(Intent.EXTRA_PROCESS_TEXT), textToBeProcessed);
 
-    // Simulate an Android activity answer which does not return any value.
+    // Simulate an Android activity answer which does not return a value.
     Intent resultIntent = new Intent();
     processTextPlugin.onActivityResult(result.hashCode(), Activity.RESULT_OK, resultIntent);
 
@@ -175,13 +175,13 @@ public void performProcessTextActionWithReturnedValue() {
     final int action2Id = 1;
     assertEquals(textActions, Map.of(action1Id, "Action1", action2Id, "Action2"));
 
-    // Set up activity binding.
+    // Set up the activity binding.
     ActivityPluginBinding mockActivityPluginBinding = mock(ActivityPluginBinding.class);
     Activity mockActivity = mock(Activity.class);
     when(mockActivityPluginBinding.getActivity()).thenReturn(mockActivity);
     processTextPlugin.onAttachedToActivity(mockActivityPluginBinding);
 
-    // Execute first action.
+    // Execute the first action.
     String textToBeProcessed = "Flutter!";
     MethodChannel.Result result = mock(MethodChannel.Result.class);
     processTextPlugin.processTextAction(action1Id, textToBeProcessed, false, result);