Added proper doxygen documentation to the file ocresourcehandler.h.

Change-Id: Iaef7aa463856615bfe4696cb3ec517e18188f28d
Signed-off-by: Joseph Morrow <joseph.l.morrow@intel.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/491
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Sudarshan Prasad <sudarshan.prasad@intel.com>
Reviewed-by: Erich Keane <erich.keane@intel.com>

diff --git a/resource/csdk/stack/include/internal/ocresourcehandler.h b/resource/csdk/stack/include/internal/ocresourcehandler.h
index 7a2859e..67bae55 100644 (file)
--- a/resource/csdk/stack/include/internal/ocresourcehandler.h
+++ b/resource/csdk/stack/include/internal/ocresourcehandler.h
@@ -25,6 +25,9 @@
 #include "ocstackinternal.h"
 #include "ocserverrequest.h"
 
+/**
+ * Attributes used to form a proper OIC conforming JSON message.
+ */
 #define OC_RSRVD_OC                     "oc"
 #define OC_RSRVD_PAYLOAD                "payload"
 #define OC_RSRVD_HREF                   "href"
@@ -39,7 +42,6 @@
 #define OC_RSRVD_INTERFACE_LL           "oc.mi.ll"
 #define OC_RSRVD_INTERFACE_BATCH        "oc.mi.b"
 #define OC_RSRVD_INTERFACE_GROUP        "oc.mi.grp"
-
 #define OC_RSRVD_MFG_DATE               "mndt"
 #define OC_RSRVD_FW_VERSION             "mnfv"
 #define OC_RSRVD_HOST_NAME              "hn"
@@ -49,13 +51,14 @@
 #define OC_RSRVD_PLATFORM_VERSION       "mnpv"
 #define OC_RSRVD_SUPPORT_URL            "mnsl"
 #define OC_RSRVD_VERSION                "icv"
-
-
 #define OC_RSRVD_OBSERVABLE             "obs"
 #define OC_RSRVD_SECURE                 "sec"
 #define OC_RSRVD_HOSTING_PORT           "port"
 #define OC_RSRVD_SERVER_INSTANCE_ID     "sid"
 
+/**
+ * Common JSON string components used by the stack to build JSON strings.
+ */
 #define OC_JSON_PREFIX                     "{\"oc\":["
 #define OC_JSON_PREFIX_LEN                 (sizeof(OC_JSON_PREFIX) - 1)
 #define OC_JSON_SUFFIX                     "]}"
@@ -63,9 +66,15 @@
 #define OC_JSON_SEPARATOR                  ','
 #define OC_JSON_SEPARATOR_STR              ","
 
+/**
+ * Static values for various JSON attributes.
+ */
 #define OC_RESOURCE_OBSERVABLE   1
 #define OC_RESOURCE_SECURE       1
 
+/**
+ * The type of query a request/response message is.
+ */
 typedef enum
 {
     STACK_RES_DISCOVERY_NOFILTER = 0,
@@ -75,6 +84,9 @@ typedef enum
     STACK_DEVICE_DISCOVERY_DN_FILTER
 } StackQueryTypes;
 
+/**
+ * The type of handling required to handle a request.
+ */
 typedef enum
 {
     OC_RESOURCE_VIRTUAL = 0,
@@ -86,29 +98,71 @@ typedef enum
     OC_RESOURCE_NOT_SPECIFIED
 } ResourceHandling;
 
+/**
+ * Default entity handler (ie. callback) to be used for resources with
+ * no entity handler.
+ */
 OCEntityHandlerResult defaultResourceEHandler(OCEntityHandlerFlag flag,
         OCEntityHandlerRequest * request);
 
-const char * GetVirtualResourceUri( OCVirtualResources resource);
+/**
+ * Get string value associated with a virtual resource type.
+ */
+const char * GetVirtualResourceUri(OCVirtualResources resource);
+
+/**
+ * Find and retrieve pointer to a resource associated with a specific resource
+ * URI.
+ */
 OCResource *FindResourceByUri(const char* resourceUri);
-uint8_t IsVirtualResource(const char* resourceUri);
 
+/**
+ * Returns true if the specificed resource URI aligns with a pre-existing
+ * virtual resource; returns false otherwise.
+ */
+bool IsVirtualResource(const char* resourceUri);
+
+/**
+ * Parameter @ref handling returns by-reference the type of resource handling
+ * required by the internal stack based on the specified @ref request.
+ */
 OCStackResult DetermineResourceHandling (OCServerRequest *request,
                                          ResourceHandling *handling,
                                          OCResource **resource);
 
-OCStackResult
-ProcessRequest(ResourceHandling resHandling, OCResource *resource, OCServerRequest *request);
-
+/**
+ * Processes the specified @ref request based on the type of resource handling
+ * @ref resHandling.
+ */
+OCStackResult ProcessRequest(ResourceHandling resHandling,
+                             OCResource *resource,
+                             OCServerRequest *request);
+
+/**
+ * Internal API used to save all of the device's information for use in device
+ * discovery requests.
+ */
 OCStackResult SaveDeviceInfo(OCDeviceInfo deviceInfo);
 
+/**
+ * Internal API used to clear the device information.
+ */
 void DeleteDeviceInfo();
 
-OCStackResult
-BuildVirtualResourceResponse(OCResource *resourcePtr, uint8_t filterOn,
-                        char *filterValue, char * out, uint16_t *remaining,
-                        CAConnectivityType_t connType );
-
+/**
+ * Prepares a JSON string for response.
+ */
+OCStackResult BuildVirtualResourceResponse(OCResource *resourcePtr,
+                                           uint8_t filterOn,
+                                           char *filterValue,
+                                           char * out,
+                                           uint16_t *remaining,
+                                           CAConnectivityType_t connType);
+
+/**
+ * A helper function that Maps an @ref OCEntityHandlerResult type to an
+ * @ref OCStackResult type.
+ */
 OCStackResult EntityHandlerCodeToOCStackCode(OCEntityHandlerResult ehResult);
 
 #endif //OC_RESOURCEHANDLER_H

diff --git a/resource/csdk/stack/src/ocresource.c b/resource/csdk/stack/src/ocresource.c
index bc440c8..f022841 100644 (file)
--- a/resource/csdk/stack/src/ocresource.c
+++ b/resource/csdk/stack/src/ocresource.c
@@ -395,21 +395,21 @@ const char * GetVirtualResourceUri( OCVirtualResources resource)
     return NULL;
 }
 
-uint8_t IsVirtualResource(const char* resourceUri)
+bool IsVirtualResource(const char* resourceUri)
 {
     if(!resourceUri)
     {
-        return 0;
+        return false;
     }
 
     for (int i = 0; i < OC_MAX_VIRTUAL_RESOURCES; i++)
     {
         if (strcmp(resourceUri, GetVirtualResourceUri((OCVirtualResources)i)) == 0)
         {
-            return 1;
+            return true;
         }
     }
-    return 0;
+    return false;
 }
 
 uint8_t IsCollectionResource (OCResource *resource)