helper: table: fix the doxygen warning

Signed-off-by: huanggaoyang <huanggaoyang1@huawei.com>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

3 files changed, 72 insertions, 62 deletions

diff --git a/helper/hashtable.c b/helper/hashtable.c
index e49c63be2..0b29814e5 100644
--- a/helper/hashtable.c
+++ b/helper/hashtable.c
@@ -31,9 +31,9 @@
  * into a list
  */
 typedef struct odph_hash_node {
-	/**< list structure,for list opt */
+	/** list structure,for list opt */
 	odph_list_object list_node;
-	/**< Flexible Array,memory will be alloced when table has been created
+	/** Flexible Array,memory will be alloced when table has been created
 	 * Its length is key_size + value_size,
 	 * suppose key_size = m; value_size = n;
 	 * its structure is like:
@@ -47,15 +47,15 @@ typedef struct {
 	uint32_t key_size; /**< input param when create,in Bytes */
 	uint32_t value_size; /**< input param when create,in Bytes */
 	uint32_t init_cap; /**< input param when create,in Bytes */
-	/**< multi-process support,every list has one rw lock */
+	/** multi-process support,every list has one rw lock */
 	odp_rwlock_t *lock_pool;
-	/**< table bucket pool,every hash value has one list head */
+	/** table bucket pool,every hash value has one list head */
 	odph_list_head *list_head_pool;
-	/**< number of the list head in list_head_pool */
+	/** number of the list head in list_head_pool */
 	uint32_t head_num;
-	/**< table element pool */
+	/** table element pool */
 	odph_hash_node *hash_node_pool;
-	/**< number of element in the hash_node_pool */
+	/** number of element in the hash_node_pool */
 	uint32_t hash_node_num;
 	char rsv[7]; /**< Reserved,for alignment */
 	char name[ODPH_TABLE_NAME_LEN]; /**< table name */
diff --git a/helper/include/odp/helper/table.h b/helper/include/odp/helper/table.h
index a1d3a0c7c..50a6a8403 100644
--- a/helper/include/odp/helper/table.h
+++ b/helper/include/odp/helper/table.h
@@ -9,6 +9,9 @@
  *
  * ODP table
  *
+ * TCAM(Ternary Content Addressable Memory) is used widely in packet
+ * forwarding to speedup the table lookup.
+ *
  * This file contains a simple interface for creating and using the table.
  * Table here means a collection of related data held in a structured
  * format.
@@ -18,8 +21,7 @@
  * Enclosed are some classical table examples, used publicly
  * in data plane packet processing:
  *
- * <Use Case> ARP table
- * <Description>
+ * <H3>Use Case: ARP table</H3>
  *   Once a route has been identified for an IP packet (so the output
  *   interface and the IP address of the next hop station are known),
  *   the MAC address of the next hop station is needed in order to
@@ -27,33 +29,36 @@
  *   towards its destination (as identified by its destination IP address).
  *   The MAC address of the next hop station becomes the destination
  *   MAC address of the outgoing Ethernet frame.
- * <key> The pair of (Output interface, Next Hop IP address)
- * <associated data> MAC address of the next hop station
- * <Algorithm> Hash
+ *   <ol>
+ *   <li>Key: The pair of (Output interface, Next Hop IP address)
+ *   <li>Associated Data: MAC address of the next hop station
+ *   <li>Algorithm: Hash
+ *	 </ol>
  *
- * <Use Case> Routing Table
- * <Description>
+ * <H3>Use Case: Routing Table</H3>
  *   When each router receives a packet, it searches its routing table
  *   to find the best match between the destination IP address of
  *   the packet and one of the network addresses in the routing table.
- * <Key> destination IP address
- * <Associated Data> The pair of (Output interface, Next Hop IP address)
- * <Algorithm> LPM(Longest Prefix Match)
- *
+ *   <ol>
+ *   <li>Key: destination IP address
+ *   <li>Associated Data: The pair of (Output interface, Next Hop IP address)
+ *   <li>Algorithm: LPM(Longest Prefix Match)
+ *   </ol>
  *
- * <Use Case> Flow Classification
- * <Description>
+ * <H3>Use Case: Flow Classification</H3>
  *   The flow classification is executed at least once for each
  *   input packet.This operation maps each incoming packet against
  *   one of the known traffic
  *   flows in the flow database that typically contains millions of flows.
- * <key> n-tuple of packet fields that uniquely identify a traffic flow.
- * <associated data>
- *   actions and action meta-data describing what processing to be
- *   applied for the packets of the current flow, such as whether
- *   encryption/decryption is required on this packet, what kind of cipher
- *   algorithm should be chosed.
- * <algorithm> Hash
+ *   <ol>
+ *   <li>Key:n-tuple of packet fields that uniquely identify a traffic flow.
+ *   <li>Associated data:
+ *     actions and action meta-data describing what processing to be
+ *     applied for the packets of the current flow, such as whether
+ *     encryption/decryption is required on this packet, what kind of cipher
+ *     algorithm should be chosed.
+ *   <li>Algorithm: Hash
+ *   </ol>
  *
  *  All these different types of lookup tables have the common operations:
  *    create a table, destroy a table, add (key,associated data),
@@ -75,8 +80,13 @@
 extern "C" {
 #endif
 
+/**
+ * @def ODPH_TABLE_NAME_LEN
+ * Max length of table name
+ */
 #define ODPH_TABLE_NAME_LEN      32
 
+/** ODP table handle */
 typedef ODP_HANDLE_T(odph_table_t);
 
 /**
@@ -104,51 +114,49 @@ typedef odph_table_t (*odph_table_create)(const char *name,
 /**
  * Find a table by name
  *
- * @param name:      Name of the table
+ * @param name      Name of the table
  *
  * @return Handle of found table
  * @retval NULL  table could not be found
  *
- * @note
- *     This routine cannot be used to look up an anonymous
- *     table (one created with no name).
- *     This API supports Multiprocess
+ * @note This routine cannot be used to look up an anonymous
+ *       table (one created with no name).
+ *       This API supports Multiprocess
  */
 typedef odph_table_t (*odph_table_lookup)(const char *name);
 
 /**
  * Destroy a table previously created by odph_table_create()
  *
- * @param table: Handle of the table to be destroyed
+ * @param table  Handle of the table to be destroyed
  *
  * @retval 0 Success
  * @retval -1 Failure
  *
- * @note
- *      This routine destroys a previously created pool
- *      also should free any memory allocated at creation
+ * @note This routine destroys a previously created pool
+ *       also should free any memory allocated at creation
  *
  */
 typedef int (*odph_table_destroy)(odph_table_t table);
 
 /**
- * Add <key,associated data> pair into the specific table.
+ * Add (key,associated data) pair into the specific table.
  * When no associated data is currently assocated with key,
- * then the <key,assocatied data> association is created.
- * When key is already associated with data0, then association <key, data0>
- * will be removed and association <key, associated data> is created.
+ * then the (key,assocatied data) association is created.
+ * When key is already associated with data0, then association (key, data0)
+ * will be removed and association (key, associated data) is created.
  *
- * @param table: Handle of the table that the element be added
+ * @param table  Handle of the table that the element be added
  *
- * @param key : address of 'key' in key-value pair.
+ * @param key   address of 'key' in key-value pair.
  *              User should make sure the address and 'key_size'
  *              bytes after are accessible
- * @param value : address of 'value' in key-value pair
+ * @param value address of 'value' in key-value pair
  *              User should make sure the address and 'value_size'
  *              bytes after are accessible
  * @retval 0 Success
  * @retval -1 Failure
- * @note: Add a same key again with a new value, the older one will
+ * @note  Add a same key again with a new value, the older one will
  *        be covered.
  */
 typedef int (*odph_table_put_value)(odph_table_t table, void *key,
@@ -160,25 +168,25 @@ typedef int (*odph_table_put_value)(odph_table_t table, void *key,
  * restuns <0 to indicate the lookup miss.
  * When key is associated with value,
  * then this operation returns value.
- * The <key,value> association won't change.
+ * The (key,value) association won't change.
  *
- * @param table: Handle of the table that the element be added
+ * @param table  Handle of the table that the element be added
  *
- * @param key : address of 'key' in key-value pair
+ * @param key   address of 'key' in key-value pair
  *              User should make sure the address and key_size bytes after
  *              are accessible
  *
- * @param buffer : output The buffer address to the 'value'
+ * @param buffer   output The buffer address to the 'value'
  *                 After successfully found, the content of 'value' will be
  *                 copied to this address
  *                 User should make sure the address and value_size bytes
  *                 after are accessible
- * @param buffer_size: size of the buffer
+ * @param buffer_size  size of the buffer
  *                     should be equal or bigger than value_size
  * @retval 0 Success
  * @retval -1 Failure
  *
- * @note:
+ * @note
  */
 typedef int (*odph_table_get_value)(odph_table_t table, void *key,
 						void *buffer,
@@ -187,30 +195,33 @@ typedef int (*odph_table_get_value)(odph_table_t table, void *key,
  * Delete the association specified by key
  * When no data is currently associated with key, this operation
  * has no effect. When key is already associated data ad0,
- * then <key,ad0> pair is deleted.
+ * then (key,ad0) pair is deleted.
  *
- * @param table: Handle of the table that the element will be removed from
+ * @param table Handle of the table that the element will be removed from
  *
- * @param key : address of 'key' in key-value pair
+ * @param key   address of 'key' in key-value pair
  *              User should make sure the address and key_size bytes after
  *              are accessible
  *
  * @retval 0 Success
  * @retval -1 Failure
  *
- * @note:
+ * @note
  */
 typedef int (*odph_table_remove_value)(odph_table_t table, void *key);
 
+/**
+ * Table interface set. Defining the table operations.
+ */
 typedef struct odp_table_ops {
 	odph_table_create        f_create;       /**< Table Create */
 	odph_table_lookup        f_lookup;       /**< Table Lookup */
 	odph_table_destroy       f_des;          /**< Table Destroy */
-	/**< add <key,associated data> into the specific table */
+	/** add (key,associated data) pair into the specific table */
 	odph_table_put_value     f_put;
-	/**< lookup the associated data via specific key */
+	/** lookup the associated data via specific key */
 	odph_table_get_value     f_get;
-	/**< delete the association specified by key. */
+	/** delete the association specified by key */
 	odph_table_remove_value  f_remove;
 } odph_table_ops_t;
 
diff --git a/helper/lineartable.c b/helper/lineartable.c
index 4dacdb31d..7809a52ca 100644
--- a/helper/lineartable.c
+++ b/helper/lineartable.c
@@ -20,7 +20,7 @@
  */
 #define     ODPH_LINEAR_TABLE_MAGIC_WORD   0xEFEFFEFE
 
-/**< @internal table struct
+/** @internal table struct
  *   For linear table, value is orgnized as a big array,
  *   and key is the index of this array, so we just need to record the
  *   content of value, and make sure the key won't overflow
@@ -28,12 +28,11 @@
 typedef struct {
 	uint32_t magicword; /**< for check */
 	uint32_t init_cap; /**< input param of capacity */
-	/**< given the capacity, caculate out the max supported nodes number */
+	/** given the capacity, caculate out the max supported nodes number */
 	uint32_t node_sum;
-	/**< size of a lineartable element,including the rwlock in the head */
+	/** size of a lineartable element,including the rwlock in the head */
 	uint32_t value_size;
-	/**< value pool in array format */
-	void *value_array;
+	void *value_array; /**< value pool in array format */
 	char name[ODPH_TABLE_NAME_LEN]; /**< name of the table */
 } odph_linear_table_imp;