odp doxygen: fix doxygen-run generated warnings

According to the CI job for ODP API doxygen generation [1], there are 28 total
warnings that needed to be fixed. This patch resolved these warnings by adding the
proper doxygen tags that were missing.

[1]: https://ci.linaro.org/view/lng-ci/job/odp-api-doxygen-generation/

Signed-off-by: Aws Ismail <aws.ismail@windriver.com>
Reviewed-by: Anders Roxell <anders.roxell@linaro.org>
Reviewed & Tested-by: Mike Holmes <mike.holmes@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

4 files changed, 107 insertions, 3 deletions

diff --git a/example/l2fwd/odp_l2fwd.c b/example/l2fwd/odp_l2fwd.c
index f89ea7a1a..d74449ac5 100644
--- a/example/l2fwd/odp_l2fwd.c
+++ b/example/l2fwd/odp_l2fwd.c
@@ -21,14 +21,40 @@
 #include <helper/odp_eth.h>
 #include <helper/odp_ip.h>
 
+/** @def MAX_WORKERS
+ * @brief Maximum number of worker threads
+ */
 #define MAX_WORKERS            32
+
+/** @def SHM_PKT_POOL_SIZE
+ * @brief Size of the shared memory block
+ */
 #define SHM_PKT_POOL_SIZE      (512*2048)
+
+/** @def SHM_PKT_POOL_BUF_SIZE
+ * @brief Buffer size of the packet pool buffer
+ */
 #define SHM_PKT_POOL_BUF_SIZE  1856
+
+/** @def MAX_PKT_BURST
+ * @brief Maximum number of packet bursts
+ */
 #define MAX_PKT_BURST          16
 
+/** @def APPL_MODE_PKT_BURST
+ * @brief The application will handle pakcets in bursts
+ */
 #define APPL_MODE_PKT_BURST    0
+
+/** @def APPL_MODE_PKT_QUEUE
+ * @brief The application will handle packets in queues
+ */
 #define APPL_MODE_PKT_QUEUE    1
 
+/** @def PRINT_APPL_MODE(x)
+ * @brief Macro to print the current status of how the application handles
+ * packets.
+ */
 #define PRINT_APPL_MODE(x) printf("%s(%i)\n", #x, (x))
 
 /** Get rid of path in filename - only for unix-type paths using '/' */
@@ -73,6 +99,7 @@ typedef struct {
 
 /** Global pointer to args */
 static args_t *gbl_args;
+/** Number of worker threads */
 static int num_workers;
 
 /* helper funcs */
@@ -82,11 +109,15 @@ static void print_info(char *progname, appl_args_t *appl_args);
 static void usage(char *progname);
 
 /**
+ * @fn static burst_mode_init_params(void *arg, odp_buffer_pool_t pool)
+ *
  * Burst mode: pktio for each thread will be created with either same or
  * different params
  *
  * @param arg  thread arguments of type 'thread_args_t *'
  * @param pool is the packet pool from where buffers should be taken
+ *
+ * @return odp_pktio_t ODP packet IO handle
  */
 static odp_pktio_t burst_mode_init_params(void *arg, odp_buffer_pool_t pool)
 {
@@ -107,11 +138,15 @@ static odp_pktio_t burst_mode_init_params(void *arg, odp_buffer_pool_t pool)
 }
 
 /**
+ * @fn queue_mode_init_params(void *arg, odp_buffer_pool_t pool)
+ *
  * Queue mode: pktio for each thread will be created with either same or
  * different params. Queues are created and attached to the pktio.
  *
  * @param arg  thread arguments of type 'thread_args_t *'
  * @param pool is the packet pool from where buffers should be taken
+ *
+ * @return odp_pktio_t ODP packet IO handle
  */
 static odp_pktio_t queue_mode_init_params(void *arg, odp_buffer_pool_t pool)
 {
diff --git a/example/odp_example/odp_example.c b/example/odp_example/odp_example.c
index be9609356..f0bdf29ec 100644
--- a/example/odp_example/odp_example.c
+++ b/example/odp_example/odp_example.c
@@ -72,7 +72,15 @@ static void clear_sched_queues(void)
 	}
 }
 
-
+/**
+ * @internal Create a single queue from a pool of buffers
+ *
+ * @param thr  Thread
+ * @param msg_pool  Buffer pool
+ * @param prio   Queue priority
+ *
+ * @return 0 if successful
+ */
 static int create_queue(int thr, odp_buffer_pool_t msg_pool, int prio)
 {
 	char name[] = "sched_XX_00";
@@ -104,6 +112,15 @@ static int create_queue(int thr, odp_buffer_pool_t msg_pool, int prio)
 	return 0;
 }
 
+/**
+ * @internal Create multiple queues from a pool of buffers
+ *
+ * @param thr  Thread
+ * @param msg_pool  Buffer pool
+ * @param prio   Queue priority
+ *
+ * @return 0 if successful
+ */
 static int create_queues(int thr, odp_buffer_pool_t msg_pool, int prio)
 {
 	char name[] = "sched_XX_YY";
diff --git a/example/packet/odp_pktio.c b/example/packet/odp_pktio.c
index 247a28a70..f247bd057 100644
--- a/example/packet/odp_pktio.c
+++ b/example/packet/odp_pktio.c
@@ -21,14 +21,40 @@
 #include <helper/odp_eth.h>
 #include <helper/odp_ip.h>
 
+/** @def MAX_WORKERS
+ * @brief Maximum number of worker threads
+ */
 #define MAX_WORKERS            32
+
+/** @def SHM_PKT_POOL_SIZE
+ * @brief Size of the shared memory block
+ */
 #define SHM_PKT_POOL_SIZE      (512*2048)
+
+/** @def SHM_PKT_POOL_BUF_SIZE
+ * @brief Buffer size of the packet pool buffer
+ */
 #define SHM_PKT_POOL_BUF_SIZE  1856
+
+/** @def MAX_PKT_BURST
+ * @brief Maximum number of packet bursts
+ */
 #define MAX_PKT_BURST          16
 
+/** @def APPL_MODE_PKT_BURST
+ * @brief The application will handle pakcets in bursts
+ */
 #define APPL_MODE_PKT_BURST    0
+
+/** @def APPL_MODE_PKT_QUEUE
+ * @brief The application will handle packets in queues
+ */
 #define APPL_MODE_PKT_QUEUE    1
 
+/** @def PRINT_APPL_MODE(x)
+ * @brief Macro to print the current status of how the application handles
+ * packets.
+ */
 #define PRINT_APPL_MODE(x) printf("%s(%i)\n", #x, (x))
 
 /** Get rid of path in filename - only for unix-type paths using '/' */
diff --git a/example/packet_netmap/odp_pktio_netmap.c b/example/packet_netmap/odp_pktio_netmap.c
index b49aa613e..c0eb2025a 100644
--- a/example/packet_netmap/odp_pktio_netmap.c
+++ b/example/packet_netmap/odp_pktio_netmap.c
@@ -29,13 +29,39 @@
 
 #include <odp_pktio_netmap.h>
 
+/** @def MAX_WORKERS
+ * @brief Maximum number of worker threads
+ */
 #define MAX_WORKERS            32
+
+/** @def MAX_IFS
+ * @brief Maximum number of netmap interfaces
+ */
 #define MAX_IFS                16
+
+/** @def SHM_PKT_POOL_SIZE
+ * @brief Size of the shared memory block
+ */
 #define SHM_PKT_POOL_SIZE      (512*2048)
+
+/** @def SHM_PKT_POOL_BUF_SIZE
+ * @brief Buffer size of the packet pool buffer
+ */
 #define SHM_PKT_POOL_BUF_SIZE  1856
+
+/** @def MAX_PKT_BURST
+ * @brief Maximum number of packet bursts
+ */
 #define MAX_PKT_BURST          16
 
+/** @def PKTIO_MODE_SOCK
+ * @brief PKTIO is set in socket mode
+ */
 #define PKTIO_MODE_SOCK        0
+
+/** @def PKTIO_MODE_NETMAP
+ * @brief PKTIO is set in netmap mode
+ */
 #define PKTIO_MODE_NETMAP      1
 
 /** Get rid of path in filename - only for unix-type paths using '/' */
@@ -46,7 +72,7 @@
  * Interface parameters obatained from app arguments
  */
 typedef struct {
-	char if_name[32];
+	char if_name[32];       /**< Interface name */
 	int pktio_mode;         /**< Socket mode or netmap mode */
 } if_info_t;
 
@@ -69,7 +95,7 @@ typedef struct {
  * defined by bridge_q below.
  */
 typedef struct {
-	odp_pktio_t pktio;
+	odp_pktio_t pktio;      /**< ODP packet IO handler */
 	odp_buffer_pool_t pool;	/**< Buffer pool for packet IO */
 	char *pktio_dev;	/**< Interface name to use */
 	int netmap_mode;	/**< Either poll the hardware rings or the