ContextHubManager: Fix API documentation. am: fac5be2ace am: 921e7ef350

am: fce14d1808

Change-Id: Ib5e0ba71519b2be92064b691c4e7d5b1b51deb81

1 files changed, 27 insertions, 3 deletions

diff --git a/core/java/android/hardware/location/ContextHubManager.java b/core/java/android/hardware/location/ContextHubManager.java
index 2aed53c7deb4..8983c326b284 100644
--- a/core/java/android/hardware/location/ContextHubManager.java
+++ b/core/java/android/hardware/location/ContextHubManager.java
@@ -118,10 +118,18 @@ public final class ContextHubManager {
     /**
      * Load a nano app on a specified context hub.
      *
+     * Note that loading is asynchronous.  When we return from this method,
+     * the nano app (probably) hasn't loaded yet.  Assuming a return of 0
+     * from this method, then the final success/failure for the load, along
+     * with the "handle" for the nanoapp, is all delivered in a byte
+     * string via a call to Callback.onMessageReceipt.
+     *
+     * TODO(b/30784270): Provide a better success/failure and "handle" delivery.
+     *
      * @param hubHandle handle of context hub to load the app on.
      * @param app the nanoApp to load on the hub
      *
-     * @return int nanoAppInstance of the loaded nanoApp on success,
+     * @return 0 if the command for loading was sent to the context hub;
      *         -1 otherwise
      *
      * @see NanoApp
@@ -137,9 +145,17 @@ public final class ContextHubManager {
     /**
      * Unload a specified nanoApp
      *
-     * @param nanoAppHandle handle of the nanoApp to load
+     * Note that unloading is asynchronous.  When we return from this method,
+     * the nano app (probably) hasn't unloaded yet.  Assuming a return of 0
+     * from this method, then the final success/failure for the unload is
+     * delivered in a byte string via a call to Callback.onMessageReceipt.
+     *
+     * TODO(b/30784270): Provide a better success/failure delivery.
      *
-     * @return int  0 on success, -1 otherwise
+     * @param nanoAppHandle handle of the nanoApp to unload
+     *
+     * @return 0 if the command for unloading was sent to the context hub;
+     *         -1 otherwise
      */
     public int unloadNanoApp(int nanoAppHandle) {
         try {
@@ -186,6 +202,14 @@ public final class ContextHubManager {
     /**
      * Send a message to a specific nano app instance on a context hub.
      *
+     * Note that the return value of this method only speaks of success
+     * up to the point of sending this to the Context Hub.  It is not
+     * an assurance that the Context Hub successfully sent this message
+     * on to the nanoapp.  If assurance is desired, a protocol should be
+     * established between your code and the nanoapp, with the nanoapp
+     * sending a confirmation message (which will be reported via
+     * Callback.onMessageReceipt).
+     *
      * @param hubHandle handle of the hub to send the message to
      * @param nanoAppHandle  handle of the nano app to send to
      * @param message Message to be sent