Update AppFunction sidecar lib Documentation

Flag: android.app.appfunctions.flags.enable_app_function_manager
Test: Existing CTS
Bug: 375121362
Change-Id: I565a875ed7966ce3b5f2b0e261ee26822bb0caca

3 files changed, 38 insertions, 52 deletions

diff --git a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/AppFunctionManager.java b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/AppFunctionManager.java
index 43377d8eb91c..6870446fc3a0 100644
--- a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/AppFunctionManager.java
+++ b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/AppFunctionManager.java
@@ -16,7 +16,6 @@
 
 package com.google.android.appfunctions.sidecar;
 
-import android.Manifest;
 import android.annotation.CallbackExecutor;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
@@ -41,8 +40,6 @@ import java.util.function.Consumer;
  * <p>This class wraps {@link android.app.appfunctions.AppFunctionManager} functionalities and
  * exposes it here as a sidecar library (avoiding direct dependency on the platform API).
  */
-// TODO(b/357551503): Implement get and set enabled app function APIs.
-// TODO(b/367329899): Add sidecar library to Android B builds.
 public final class AppFunctionManager {
     /**
      * The default state of the app function. Call {@link #setAppFunctionEnabled} with this to reset
@@ -70,9 +67,9 @@ public final class AppFunctionManager {
     @IntDef(
             prefix = {"APP_FUNCTION_STATE_"},
             value = {
-                    APP_FUNCTION_STATE_DEFAULT,
-                    APP_FUNCTION_STATE_ENABLED,
-                    APP_FUNCTION_STATE_DISABLED
+                APP_FUNCTION_STATE_DEFAULT,
+                APP_FUNCTION_STATE_ENABLED,
+                APP_FUNCTION_STATE_DISABLED
             })
     @Retention(RetentionPolicy.SOURCE)
     public @interface EnabledState {}
@@ -102,6 +99,9 @@ public final class AppFunctionManager {
      * <p>Proxies request and response to the underlying {@link
      * android.app.appfunctions.AppFunctionManager#executeAppFunction}, converting the request and
      * response in the appropriate type required by the function.
+     *
+     * <p>See {@link android.app.appfunctions.AppFunctionManager#executeAppFunction} for the
+     * documented behaviour of this method.
      */
     public void executeAppFunction(
             @NonNull ExecuteAppFunctionRequest sidecarRequest,
@@ -128,24 +128,8 @@ public final class AppFunctionManager {
     /**
      * Returns a boolean through a callback, indicating whether the app function is enabled.
      *
-     * <p>* This method can only check app functions owned by the caller, or those where the caller
-     * has visibility to the owner package and holds either the {@link
-     * Manifest.permission#EXECUTE_APP_FUNCTIONS} or {@link
-     * Manifest.permission#EXECUTE_APP_FUNCTIONS_TRUSTED} permission.
-     *
-     * <p>If operation fails, the callback's {@link OutcomeReceiver#onError} is called with errors:
-     *
-     * <ul>
-     *   <li>{@link IllegalArgumentException}, if the function is not found or the caller does not
-     *       have access to it.
-     * </ul>
-     *
-     * @param functionIdentifier the identifier of the app function to check (unique within the
-     *     target package) and in most cases, these are automatically generated by the AppFunctions
-     *     SDK
-     * @param targetPackage the package name of the app function's owner
-     * @param executor the executor to run the request
-     * @param callback the callback to receive the function enabled check result
+     * <p>See {@link android.app.appfunctions.AppFunctionManager#isAppFunctionEnabled} for the
+     * documented behaviour of this method.
      */
     public void isAppFunctionEnabled(
             @NonNull String functionIdentifier,
@@ -158,20 +142,8 @@ public final class AppFunctionManager {
     /**
      * Sets the enabled state of the app function owned by the calling package.
      *
-     * <p>If operation fails, the callback's {@link OutcomeReceiver#onError} is called with errors:
-     *
-     * <ul>
-     *   <li>{@link IllegalArgumentException}, if the function is not found or the caller does not
-     *       have access to it.
-     * </ul>
-     *
-     * @param functionIdentifier the identifier of the app function to enable (unique within the
-     *     calling package). In most cases, identifiers are automatically generated by the
-     *     AppFunctions SDK
-     * @param newEnabledState the new state of the app function
-     * @param executor the executor to run the callback
-     * @param callback the callback to receive the result of the function enablement. The call was
-     *     successful if no exception was thrown.
+     * <p>See {@link android.app.appfunctions.AppFunctionManager#setAppFunctionEnabled} for the
+     * documented behavoir of this method.
      */
     // Constants in @EnabledState should always mirror those in
     // android.app.appfunctions.AppFunctionManager.
diff --git a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionRequest.java b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionRequest.java
index fa6d2ff12313..593c5213dd52 100644
--- a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionRequest.java
+++ b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionRequest.java
@@ -34,8 +34,8 @@ public final class ExecuteAppFunctionRequest {
     @NonNull private final String mTargetPackageName;
 
     /**
-     * Returns the unique string identifier of the app function to be executed. TODO(b/357551503):
-     * Document how callers can get the available function identifiers.
+     * The unique string identifier of the app function to be executed. This identifier is used to
+     * execute a specific app function.
      */
     @NonNull private final String mFunctionIdentifier;
 
@@ -49,8 +49,6 @@ public final class ExecuteAppFunctionRequest {
      *
      * <p>The document may have missing parameters. Developers are advised to implement defensive
      * handling measures.
-     *
-     * <p>TODO(b/357551503): Document how function parameters can be obtained for function execution
      */
     @NonNull private final GenericDocument mParameters;
 
@@ -71,7 +69,19 @@ public final class ExecuteAppFunctionRequest {
         return mTargetPackageName;
     }
 
-    /** Returns the unique string identifier of the app function to be executed. */
+    /**
+     * Returns the unique string identifier of the app function to be executed.
+     *
+     * <p>When there is a package change or the device starts up, the metadata of available
+     * functions is indexed by AppSearch. AppSearch stores the indexed information as {@code
+     * AppFunctionStaticMetadata} document.
+     *
+     * <p>The ID can be obtained by querying the {@code AppFunctionStaticMetadata} documents from
+     * AppSearch.
+     *
+     * <p>If the {@code functionId} provided is invalid, the caller will get an invalid argument
+     * response.
+     */
     @NonNull
     public String getFunctionIdentifier() {
         return mFunctionIdentifier;
@@ -83,6 +93,12 @@ public final class ExecuteAppFunctionRequest {
      *
      * <p>The bundle may have missing parameters. Developers are advised to implement defensive
      * handling measures.
+     *
+     * <p>Similar to {@link #getFunctionIdentifier()} the parameters required by a function can be
+     * obtained by querying AppSearch for the corresponding {@code AppFunctionStaticMetadata}. This
+     * metadata will contain enough information for the caller to resolve the required parameters
+     * either using information from the metadata itself or using the AppFunction SDK for function
+     * callers.
      */
     @NonNull
     public GenericDocument getParameters() {
@@ -128,10 +144,7 @@ public final class ExecuteAppFunctionRequest {
         @NonNull
         public ExecuteAppFunctionRequest build() {
             return new ExecuteAppFunctionRequest(
-                    mTargetPackageName,
-                    mFunctionIdentifier,
-                    mExtras,
-                    mParameters);
+                    mTargetPackageName, mFunctionIdentifier, mExtras, mParameters);
         }
     }
 }
diff --git a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionResponse.java b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionResponse.java
index 969e5d58b909..d5dfaeb77140 100644
--- a/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionResponse.java
+++ b/libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionResponse.java
@@ -56,14 +56,15 @@ public final class ExecuteAppFunctionResponse {
     /** The caller does not have the permission to execute an app function. */
     public static final int RESULT_DENIED = 1;
 
-    /** An unknown error occurred while processing the call in the AppFunctionService. */
-    public static final int RESULT_APP_UNKNOWN_ERROR = 2;
-
     /**
-     * An internal error occurred within AppFunctionManagerService.
+     * An unknown error occurred while processing the call in the AppFunctionService.
      *
-     * <p>This error may be considered similar to {@link IllegalStateException}
+     * <p>This error is thrown when the service is connected in the remote application but an
+     * unexpected error is thrown from the bound application.
      */
+    public static final int RESULT_APP_UNKNOWN_ERROR = 2;
+
+    /** An internal unexpected error coming from the system. */
     public static final int RESULT_INTERNAL_ERROR = 3;
 
     /**