IOT-2838 Fix javadoc warnings 77/22977/3
authorGeorge Nash <george.nash@intel.com>
Mon, 23 Oct 2017 23:31:59 +0000 (16:31 -0700)
committerRick Bell <richard.s.bell@intel.com>
Wed, 25 Oct 2017 17:29:21 +0000 (17:29 +0000)
Documented all the functions referencing the native code.

Note the OcProvisioning setPinType method had a return value
int. The was returning the return value of the native call
that was the status. Due to the way the code was writen the
only value that could be returned was when things worked as
expected. All other values were thrown so the return value
was un-needed. The function was changed to have a return type
of void.

Bug:https://jira.iotivity.org/browse/IOT-2838
Change-Id: I3b5955a336661574dde9f70c87b6ead3dcd5ea7b
Signed-off-by: George Nash <george.nash@intel.com>
java/common/src/main/java/org/iotivity/base/OcProvisioning.java
java/common/src/main/java/org/iotivity/base/OcResource.java
java/common/src/main/java/org/iotivity/base/OcSecureResource.java
java/iotivity-android/src/main/java/org/iotivity/base/OcPlatform.java
java/iotivity-android/src/main/java/org/iotivity/ca/CaInterface.java
java/jni/JniOcProvisioning.cpp
java/jni/JniOcProvisioning.h
service/notification/android/notification-service/src/main/java/org/iotivity/service/ns/provider/ProviderService.java
service/resource-encapsulation/android/service/src/main/java/org/iotivity/service/client/RcsRemoteResourceObject.java

index 1095cb8..60538e8 100644 (file)
@@ -128,7 +128,7 @@ public class OcProvisioning {
      * @param timeout     Timeout in sec.Time to listen for responses before
      *                    returining the Array.
      * @return            Array of OcSecureResource class objects.
-     * @throws OcException
+     * @throws OcException Indicate failure discovering devices which are MOT enabled
      */
     public static List<OcSecureResource> discoverMOTEnabledDevices(int timeout)
         throws OcException {
@@ -143,7 +143,7 @@ public class OcProvisioning {
      * @param timeout     Timeout in sec.Time to listen for responses before
      *                    returining the Array.
      * @return            Array of OcSecureResource class objects.
-     * @throws OcException
+     * @throws OcException Indicate failure discovering MOT enabled owned devices
      */
     public static List<OcSecureResource> discoverMOTEnabledOwnedDevices(int timeout)
         throws OcException {
@@ -280,9 +280,9 @@ public class OcProvisioning {
      *
      *  @param pinSize Byte Len of Random pin.
      *  @param pinType Enumset of pin, see PinType for enums
-     *  @throws OcException
+     *  @throws OcException Indicate failure saving pin type
      */
-    public static int setPinType(int pinSize, EnumSet<PinType>  pinType) throws OcException {
+    public static void setPinType(int pinSize, EnumSet<PinType>  pinType) throws OcException {
 
         int pinTypeInt = 0;
 
@@ -290,22 +290,22 @@ public class OcProvisioning {
             if (pinType.contains(ops))
                 pinTypeInt |= ops.getValue();
         }
-        return setPinType0(pinSize, pinTypeInt);
+        setPinType0(pinSize, pinTypeInt);
     }
-    private static native int setPinType0(int pinSize, int pinType) throws OcException;
+    private static native void setPinType0(int pinSize, int pinType) throws OcException;
 
     /**
      * API to save ACL, having multiple ACE's
      *
      *@param acl object
-     *@throws OcException
+     *@throws OcException Indicate failure saving the ACL
      */
     public static native void saveACL(Object acl) throws OcException;
 
     /**
      * API to do self ownership transfer.
      *
-     *@throws OcException
+     *@throws OcException Indicate failure doing the self ownership transfer
      */
     public static native void doSelfOwnershiptransfer() throws OcException;
     
@@ -313,7 +313,8 @@ public class OcProvisioning {
      *  Method to save the seed value to generate device UUID
      *
      *  @param seed   buffer of seed value
-     *  @throws OcException
+     *  @throws OcException Indicate falure setting the device UUID seed
+     *  @return -1 if TLS not enabled return 0 otherwise
      */
     public static int setDeviceIdSeed(byte[] seed) throws OcException {
         return setDeviceIdSeed1(seed);
index 6224c7c..49b0409 100644 (file)
@@ -562,6 +562,7 @@ public class OcResource {
 
     /**
      * Function to change host of this reource
+     * @param host host address to change to
      * @return New host Address.
      *         Not observable.
      */
index 0abaf3f..9f6329f 100644 (file)
@@ -197,7 +197,7 @@ public class OcSecureResource {
      * @param oxmType Method to be selected
      * @param selectOTMMethodListener Callback function, which will be called after completion
      *
-     * @throws OcException
+     * @throws OcException Indicate failure selecting OTM method
      */
     public void selectMOTMethod(OxmType oxmType,
             SelectOTMMethodListener selectOTMMethodListener) throws OcException {
@@ -213,7 +213,7 @@ public class OcSecureResource {
      * @param momType MOT mode to be selected.
      * @param changeMOTModeListener Callback function, which will be called after completion
      *
-     * @throws OcException
+     * @throws OcException Indicate failure changing the MOT mode
      */
     public void changeMOTMode(MomType momType,
             ChangeMOTModeListener changeMOTModeListener) throws OcException {
@@ -228,7 +228,7 @@ public class OcSecureResource {
      *
      * @param pin string to be saved in svr db.
      *
-     * @throws OcException
+     * @throws OcException Indicate failure adding PIN
      */
     public void addPreConfigPIN(String pin) throws OcException {
         this.addPreConfigPIN0(pin, pin.length());
@@ -243,7 +243,7 @@ public class OcSecureResource {
      * @param provisionPreConfigPINListener Callback function, which will be called after
      *                                      completion
      *
-     * @throws OcException
+     * @throws OcException Indicate failure provisioning PIN
      */
     public void  provisionPreConfigPIN(String pin,
             ProvisionPreConfigPINListener provisionPreConfigPINListener) throws OcException {
index 8c2cd6a..37c88b6 100644 (file)
@@ -1262,11 +1262,14 @@ public final class OcPlatform {
 
     /**
      * Method to set DeviceId.
+     * @param deviceId DeviceId of the client
+     * @throws OcException if failure
      */
     public static native void setDeviceId(byte[] deviceId) throws OcException;
 
     /**
      * Method to get the version of IoTivity.
+     * @return the version of IoTivity
      */
     public static native String getIoTivityVersion();
 }
index 5cad309..90c2f8d 100644 (file)
@@ -257,6 +257,15 @@ public class CaInterface {
 
     /**
      *  set BT configure
+     *  flags for BLE transport
+     *  {@code
+     *    0:        default BT flag
+     *    0x1:      disable BLE advertisement.
+     *    0x2:      enable BLE advertisement.
+     *    (1 << 4): disable gatt server.
+     *    (1 << 7): disable EDR transport.
+     *  }
+     *  @param flag use value indicated above
      */
     public synchronized static void setBTConfigure(int flag){
         CaInterface.setBTConfigureImpl(flag);
@@ -271,6 +280,7 @@ public class CaInterface {
     /**
      * Set Connection Manager configuration.
      * It can be set a connection manager configuration.(default: CA_CLOUD)
+     * @param connPriority User Preference of connectivity channel for connection manager
      */
     public synchronized static void setConnectionUserConfig(CaIpConnectionPreference connPriority) {
         CaInterface.caManagerSetConnectionUserConfig(connPriority.getValue());
index d99ad45..6b58ed9 100644 (file)
@@ -376,7 +376,7 @@ JNIEXPORT jint JNICALL Java_org_iotivity_base_OcProvisioning_unsetDisplayNumList
  * Method:    setPinType0
  * Signature: (II)I
  */
-JNIEXPORT jint JNICALL Java_org_iotivity_base_OcProvisioning_setPinType0
+JNIEXPORT void JNICALL Java_org_iotivity_base_OcProvisioning_setPinType0
   (JNIEnv *env, jclass thiz, jint pinSize, jint pinType)
 {
     OC_UNUSED(thiz);
@@ -396,7 +396,7 @@ JNIEXPORT jint JNICALL Java_org_iotivity_base_OcProvisioning_setPinType0
         LOGE("%s", e.reason().c_str());
         ThrowOcException(OC_STACK_ERROR, e.reason().c_str());
     }
-    return result;
+    return;
 }
 
 /*
index 12dae0a..f6fdd3b 100644 (file)
@@ -159,7 +159,7 @@ JNIEXPORT jint JNICALL Java_org_iotivity_base_OcProvisioning_saveTrustCertChain1
  * Method:    setPinType0
  * Signature: (II)I
  */
-JNIEXPORT jint JNICALL Java_org_iotivity_base_OcProvisioning_setPinType0
+JNIEXPORT void JNICALL Java_org_iotivity_base_OcProvisioning_setPinType0
   (JNIEnv *, jclass, jint, jint);
 
 
index 8f7969e..9a583fb 100755 (executable)
@@ -204,7 +204,7 @@ public class ProviderService {
     /**
      * Request topics list already registered by provider user
      *
-     *
+     * @return topics list
      * @throws NSException failed to get topics list
      */
     public TopicsList getRegisteredTopicList() throws NSException {
index 8d82606..9f8d1a8 100644 (file)
@@ -144,8 +144,8 @@ public final class RcsRemoteResourceObject extends RcsObject {
         /**
          * Called when the cache is updated.
          *
-         * @param attributes
-         *            the updated attributes
+         * @param attributes the updated attributes
+         * @param eCode Cache updated error code 
          *
          */
         public void onCacheUpdated(RcsResourceAttributes attributes, int eCode);