[Doc] update API description

Code clean, update tags and API description.

Signed-off-by: Jaeyun Jung <[email protected]>

include/nnstreamer-edge-data.h

@@ -27,15 +27,15 @@ typedef int64_t nns_ssize_t;
  * @brief The maximum number of data instances that nnstreamer-edge data may have.
  */
 #define NNS_EDGE_DATA_LIMIT (256)
+
 /**
  * @brief Callback called when nnstreamer-edge data is released.
  */
 typedef void (*nns_edge_data_destroy_cb) (void *data);
 
-
 /**
  * @brief Create a handle used for data transmission.
- * @note Caller should release returned edge data using nns_edge_data_destroy().
+ * @remarks If the function succeeds, @a data_h should be released using nns_edge_data_destroy().
  * @param[out] data_h Handle of edge data.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
@@ -55,9 +55,19 @@ int nns_edge_data_create (nns_edge_data_h *data_h);
  */
 int nns_edge_data_destroy (nns_edge_data_h data_h);
 
+/**
+ * @brief Destroy nnstreamer edge data handle.
+ * @details This is wrapper function of nns_edge_data_destroy() to avoid build warning of the incompatibe type casting.
+ * @param[in] data The pointer to the edge data handle to be released.
+ * @retval #NNS_EDGE_ERROR_NONE Successful.
+ * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
+ * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
+ */
+void nns_edge_data_release_handle (void *data);
+
 /**
  * @brief Copy edge data and return new handle.
- * @note Caller should release returned new edge data using nns_edge_data_destroy().
+ * @remarks If the function succeeds, @a new_data_h should be released using nns_edge_data_destroy().
  * @param[in] data_h The edge data to be copied.
  * @param[out] new_data_h A destination handle of edge data.
  * @return 0 on success. Otherwise a negative error value.
@@ -132,7 +142,8 @@ int nns_edge_data_set_info (nns_edge_data_h data_h, const char *key, const char
 
 /**
  * @brief Get the information of edge data.
- * @note The param key is case-insensitive. Caller should release the returned value using free().
+ * @remarks If the function succeeds, @a value should be released using free().
+ * @note The param key is case-insensitive.
  * @param[in] data_h The edge data handle.
  * @param[in] key A key of the information.
  * @param[in] value The information to get.
@@ -153,15 +164,6 @@ int nns_edge_data_get_info (nns_edge_data_h data_h, const char *key, char **valu
  */
 int nns_edge_data_clear_info (nns_edge_data_h data_h);
 
-/**
- * @brief Release the edge data handle. This function releases the memory allocated for the edge data handle.
- * @param[in] data The pointer to the edge data handle to be released.
- * @retval #NNS_EDGE_ERROR_NONE Successful.
- * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
- * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
- */
-void nns_edge_data_release_handle (void *data);
-
 /**
  * @brief Validate edge data handle.
  * @param[in] data_h The edge data handle.
@@ -173,6 +175,7 @@ int nns_edge_data_is_valid (nns_edge_data_h data_h);
 
 /**
  * @brief Serialize metadata in edge data.
+ * @remarks If the function succeeds, @a data should be released using free().
  * @param[in] data_h The handle to the edge data.
  * @param[out] data A pointer to store the serialized meta data.
  * @param[out] data_len A pointer to store the length of the serialized meta data.
@@ -198,6 +201,7 @@ int nns_edge_data_deserialize_meta (nns_edge_data_h data_h, const void *data, co
 
 /**
  * @brief Serialize entire edge data (meta data + raw data).
+ * @remarks If the function succeeds, @a data should be released using free().
  * @param[in] data_h The handle to the edge data.
  * @param[out] data A pointer to store the serialized edge data.
  * @param[out] data_len A pointer to store the length of the serialized edge data.
@@ -228,7 +232,8 @@ int nns_edge_data_deserialize (nns_edge_data_h data_h, const void *data, const n
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
- * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */
+ * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
+ */
 int nns_edge_data_is_serialized (const void *data, const nns_size_t data_len);
 
 #ifdef __cplusplus

include/nnstreamer-edge-event.h

@@ -21,6 +21,9 @@ extern "C" {
 
 typedef void *nns_edge_event_h;
 
+/**
+ * @brief Enumeration for the event type of nnstreamer-edge.
+ */
 typedef enum {
   NNS_EDGE_EVENT_UNKNOWN = 0,
   NNS_EDGE_EVENT_CAPABILITY,
@@ -33,13 +36,11 @@ typedef enum {
 
 /**
  * @brief Callback for the nnstreamer edge event.
+ * @note This callback will suspend data stream. Do not spend too much time in the callback.
  * @param[in] event_h The edge event handle.
  * @param[in] user_data The user's custom data given to callbacks.
- * @note This callback will suspend data stream. Do not spend too much time in the callback.
  * @return 0 on success. Otherwise a negative error value.
- * @retval #NNS_EDGE_ERROR_NONE Successful.
- * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
- * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */
+ */
 typedef int (*nns_edge_event_cb) (nns_edge_event_h event_h, void *user_data);
 
 /**
@@ -55,7 +56,7 @@ int nns_edge_event_get_type (nns_edge_event_h event_h, nns_edge_event_e *event);
 
 /**
  * @brief Parse edge event (NNS_EDGE_EVENT_NEW_DATA_RECEIVED) and get received data.
- * @note Caller should release returned edge data using nns_edge_data_destroy().
+ * @remarks If the function succeeds, @a data_h should be released using nns_edge_data_destroy().
  * @param[in] event_h The edge event handle.
  * @param[out] data_h Handle of received data.
  * @return 0 on success. Otherwise a negative error value.
@@ -67,7 +68,7 @@ int nns_edge_event_parse_new_data (nns_edge_event_h event_h, nns_edge_data_h *da
 
 /**
  * @brief Parse edge event (NNS_EDGE_EVENT_CAPABILITY) and get capability string.
- * @note Caller should release returned string using free().
+ * @remarks If the function succeeds, @a capability should be released using free().
  * @param[in] event_h The edge event handle.
  * @param[out] capability Capability string.
  * @return 0 on success. Otherwise a negative error value.
@@ -94,8 +95,9 @@ int nns_edge_event_invoke_callback (nns_edge_event_cb event_cb, void *user_data,
 
 /**
  * @brief Create nnstreamer edge event.
+ * @remarks If the function succeeds, @a event_h should be released using nns_edge_event_destroy().
  * @param[in] event Edge event type.
- * @param[out] event_h The handle of the created edge event. It should be released using nns_edge_event_destroy().
+ * @param[out] event_h The handle of the created edge event.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
@@ -110,7 +112,8 @@ int nns_edge_event_create (nns_edge_event_e event, nns_edge_event_h *event_h);
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
- * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */
+ * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
+ */
 int nns_edge_event_destroy (nns_edge_event_h event_h);
 
 /**
@@ -122,7 +125,8 @@ int nns_edge_event_destroy (nns_edge_event_h event_h);
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
- * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */
+ * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
+ */
 int nns_edge_event_set_data (nns_edge_event_h event_h, void *data, nns_size_t data_len, nns_edge_data_destroy_cb destroy_cb);
 
 #ifdef __cplusplus

include/nnstreamer-edge.h

@@ -16,6 +16,7 @@
 #include <errno.h>
 #include <stdio.h>
 #include <stdlib.h>
+
 #include "nnstreamer-edge-data.h"
 #include "nnstreamer-edge-event.h"
 
@@ -38,6 +39,9 @@ typedef enum {
   NNS_EDGE_ERROR_NOT_SUPPORTED = (NNS_EDGE_ERROR_UNKNOWN + 2),
 } nns_edge_error_e;
 
+/**
+ * @brief Enumeration for the connection type of nnstreamer-edge.
+ */
 typedef enum {
   NNS_EDGE_CONNECT_TYPE_TCP = 0,
   NNS_EDGE_CONNECT_TYPE_MQTT,
@@ -48,6 +52,9 @@ typedef enum {
   NNS_EDGE_CONNECT_TYPE_UNKNOWN
 } nns_edge_connect_type_e;
 
+/**
+ * @brief Enumeration for the node type of nnstreamer-edge.
+ */
 typedef enum {
   NNS_EDGE_NODE_TYPE_QUERY_CLIENT = 0,
   NNS_EDGE_NODE_TYPE_QUERY_SERVER,
@@ -59,10 +66,11 @@ typedef enum {
 
 /**
  * @brief Create a handle representing an instance of edge-AI connection between a server and client (query) or a data publisher and scriber.
+ * @remarks If the function succeeds, @a edge_h should be released using nns_edge_release_handle().
  * @param[in] id Unique id in local network
  * @param[in] connect_type Value of @a nns_edge_connect_type_e. Connection type between edge nodes.
  * @param[in] node_type Value of @a nns_edge_node_type_e. The node type of edge connection.
- * @param[out] edge_h The edge handle. If the function succeeds, @a edge_h should be released using nns_edge_release_handle().
+ * @param[out] edge_h The edge handle.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
@@ -150,10 +158,11 @@ int nns_edge_create_handle (const char *id, nns_edge_connect_type_e connect_type
 
 /**
  * @brief Create edge custom handle.
+ * @remarks If the function succeeds, @a edge_h should be released using nns_edge_release_handle().
  * @param[in] id Unique id in local network
  * @param[in] lib_path The library path implementing the custom connection.
  * @param[in] node_type Value of @a nns_edge_node_type_e. The node type of edge connection.
- * @param[out] edge_h The edge handle. If the function succeeds, @a edge_h should be released using nns_edge_release_handle().
+ * @param[out] edge_h The edge handle.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported.
@@ -303,7 +312,8 @@ int nns_edge_set_info (nns_edge_h edge_h, const char *key, const char *value);
 
 /**
  * @brief Get nnstreamer edge info.
- * @note The param key is case-insensitive. Caller should release returned string using free().
+ * @remarks If the function succeeds, @a value should be released using free().
+ * @note The param key is case-insensitive.
  * @param[in] edge_h The edge handle.
  * @param[in] key Identifiers to determine which value to get.
  * @param[out] value The values that match the key.

src/libnnstreamer-edge/nnstreamer-edge-queue.h

@@ -14,8 +14,7 @@
 #ifndef __NNSTREAMER_EDGE_QUEUE_H__
 #define __NNSTREAMER_EDGE_QUEUE_H__
 
-#include <stdbool.h>
-#include "nnstreamer-edge.h"
+#include "nnstreamer-edge-data.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -32,7 +31,8 @@ typedef enum {
 } nns_edge_queue_leak_e;
 
 /**
- * @brief Create queue.
+ * @brief Create queue. Default length limit is 0 (unlimited).
+ * @remarks If the function succeeds, @a handle should be released using nns_edge_queue_destroy().
  * @param[out] handle Newly created handle.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
@@ -92,7 +92,7 @@ int nns_edge_queue_push (nns_edge_queue_h handle, void *data, nns_size_t size, n
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
- * @retval #NNS_EDGE_ERROR_IO
+ * @retval #NNS_EDGE_ERROR_IO Failed to get data.
  */
 int nns_edge_queue_pop (nns_edge_queue_h handle, void **data, nns_size_t *size);
 
@@ -105,17 +105,17 @@ int nns_edge_queue_pop (nns_edge_queue_h handle, void **data, nns_size_t *size);
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
- * @retval #NNS_EDGE_ERROR_IO
+ * @retval #NNS_EDGE_ERROR_IO Failed to get data.
  */
 int nns_edge_queue_wait_pop (nns_edge_queue_h handle, unsigned int timeout, void **data, nns_size_t *size);
 
 /**
  * @brief Stop waiting for new data and clear all data in the queue.
+ * @details When this function is called, nns_edge_queue_wait_pop() will stop the waiting.
  * @param[in] handle The queue handle.
  * @return 0 on success. Otherwise a negative error value.
  * @retval #NNS_EDGE_ERROR_NONE Successful.
  * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid.
- * @note When this function is called, nns_edge_queue_wait_pop will stop the waiting.
  */
 int nns_edge_queue_clear (nns_edge_queue_h handle);