Improve documentation of VirtualTouchEvent

VirtualTouchEvent.Builder raises an exception during build() that is not
obvious why it is raised. Adding documentation with explanation.

Test: pure documentation change
Change-Id: I877fd17dd8325ff614ea056aa005740c1a25da1f

core/java/android/hardware/input/VirtualTouchEvent.java

@@ -33,6 +33,11 @@ import java.lang.annotation.RetentionPolicy;
  * The pointer id, tool type, action, and location are required; pressure and main axis size are
  * optional.
  *
+ * Note: A VirtualTouchEvent with ACTION_CANCEL can only be created with TOOL_TYPE_PALM (and vice
+ * versa). Events are injected into the uinput kernel module, which has no concept of cancelling
+ * an action. The only way to state the intention that a pointer should not be handled as a pointer
+ * is to change its tool type to TOOL_TYPE_PALM.
+ *
  * @hide
  */
 @SystemApi
@@ -186,6 +191,10 @@ public final class VirtualTouchEvent implements Parcelable {
 
         /**
          * Creates a {@link VirtualTouchEvent} object with the current builder configuration.
+         *
+         * @throws IllegalArgumentException if one of the required arguments is missing or if
+         * ACTION_CANCEL is not set in combination with TOOL_TYPE_PALM. See
+         * {@link VirtualTouchEvent} for a detailed explanation.
          */
         public @NonNull VirtualTouchEvent build() {
             if (mToolType == TOOL_TYPE_UNKNOWN || mPointerId == MotionEvent.INVALID_POINTER_ID

core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java

@@ -136,6 +136,12 @@ public class VirtualTouchEventTest {
                 .build());
     }
 
+    /**
+     * The combination of TOOL_TYPE_PALM with anything else than ACTION_CANCEL should throw an
+     * exception. This is due to an underlying implementation detail. See documentation of {@link
+     * VirtualTouchEvent}
+     * for details.
+     */
     @Test
     public void touchEvent_palmUsedImproperly() {
         assertThrows(IllegalArgumentException.class, () -> new VirtualTouchEvent.Builder()