From fac5be2ace153998d8d317c76a22dffe9bf17f34 Mon Sep 17 00:00:00 2001
From: Greg Kaiser <gkaiser@google.com>
Date: Wed, 17 Aug 2016 15:33:10 -0700
Subject: ContextHubManager: Fix API documentation.

Most notably, the loadNanoApp() claimed it was returning the
nano app instance handle on success, when it actually was just
returning 0 on success.

Bug: 30475803
Change-Id: I436255f0103a743a02f40c41ee4c6f653d007d89
---
 .../hardware/location/ContextHubManager.java       | 30 +++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/core/java/android/hardware/location/ContextHubManager.java b/core/java/android/hardware/location/ContextHubManager.java
index 0c3d4b3d7be6..72ce997c7f1b 100644
--- a/core/java/android/hardware/location/ContextHubManager.java
+++ b/core/java/android/hardware/location/ContextHubManager.java
@@ -123,10 +123,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
@@ -150,9 +158,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) {
         int retVal = -1;
@@ -209,6 +225,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
-- 
cgit v1.2.3-59-g8ed1b