[1/1] lib: fix doxygen for parameters of function pointers

Message ID 20210121231533.381590-1-thomas@monjalon.net (mailing list archive)
State Accepted, archived
Delegated to: Thomas Monjalon
Headers
Series [1/1] lib: fix doxygen for parameters of function pointers |

Checks

Context Check Description
ci/checkpatch warning coding style issues
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-intel-Performance fail Performance Testing issues
ci/iol-intel-Functional success Functional Testing PASS
ci/iol-mellanox-Functional success Functional Testing PASS
ci/iol-testing warning Testing issues

Commit Message

Thomas Monjalon Jan. 21, 2021, 11:15 p.m. UTC
  Some parameters of typedef'ed function pointers were not properly listed
in the doxygen comments.
The error is seen with doxygen 1.9 which added this specific check:
	https://github.com/doxygen/doxygen/commit/d34236ba4037

Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 lib/librte_compressdev/rte_compressdev_pmd.h |  2 ++
 lib/librte_cryptodev/rte_cryptodev_pmd.h     | 12 ++++++------
 lib/librte_eal/include/rte_keepalive.h       |  2 +-
 lib/librte_eventdev/rte_eventdev_pmd.h       | 12 +++++++++++-
 lib/librte_port/rte_port.h                   |  2 +-
 lib/librte_port/rte_swx_port.h               |  4 ++--
 lib/librte_rawdev/rte_rawdev_pmd.h           | 18 ++++++++++++------
 lib/librte_security/rte_security_driver.h    |  7 ++++---
 lib/librte_table/rte_swx_table.h             |  6 ------
 lib/librte_table/rte_table.h                 |  4 ++--
 10 files changed, 41 insertions(+), 28 deletions(-)
  

Comments

Thomas Monjalon Jan. 29, 2021, 2:58 p.m. UTC | #1
22/01/2021 00:15, Thomas Monjalon:
> Some parameters of typedef'ed function pointers were not properly listed
> in the doxygen comments.
> The error is seen with doxygen 1.9 which added this specific check:
> 	https://github.com/doxygen/doxygen/commit/d34236ba4037
> 
> Cc: stable@dpdk.org
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>

No comment after a week,
I won't wait more because it is a blocker with recent version of doxygen.

Applied
  

Patch

diff --git a/lib/librte_compressdev/rte_compressdev_pmd.h b/lib/librte_compressdev/rte_compressdev_pmd.h
index d5898a5b71..52e64eab03 100644
--- a/lib/librte_compressdev/rte_compressdev_pmd.h
+++ b/lib/librte_compressdev/rte_compressdev_pmd.h
@@ -138,6 +138,8 @@  typedef void (*compressdev_stats_reset_t)(struct rte_compressdev *dev);
  *
  * @param dev
  *   Compress device
+ * @param dev_info
+ *   Compress device informations to populate
  */
 typedef void (*compressdev_info_get_t)(struct rte_compressdev *dev,
 				struct rte_compressdev_info *dev_info);
diff --git a/lib/librte_cryptodev/rte_cryptodev_pmd.h b/lib/librte_cryptodev/rte_cryptodev_pmd.h
index 9a8a7e632b..1274436870 100644
--- a/lib/librte_cryptodev/rte_cryptodev_pmd.h
+++ b/lib/librte_cryptodev/rte_cryptodev_pmd.h
@@ -121,7 +121,7 @@  extern struct rte_cryptodev *rte_cryptodevs;
  *	Function used to configure device.
  *
  * @param	dev	Crypto device pointer
- *		config	Crypto device configurations
+ * @param	config	Crypto device configurations
  *
  * @return	Returns 0 on success
  */
@@ -176,7 +176,8 @@  typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
 /**
  * Function used to get specific information of a device.
  *
- * @param	dev	Crypto device pointer
+ * @param	dev		Crypto device pointer
+ * @param	dev_info	Pointer to infos structure to populate
  */
 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
 				struct rte_cryptodev_info *dev_info);
@@ -213,7 +214,7 @@  typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
  *
  * @param	dev		Crypto device pointer
  * @param	nb_objs		number of sessions objects in mempool
- * @param	obj_cache	l-core object cache size, see *rte_ring_create*
+ * @param	obj_cache_size	l-core object cache size, see *rte_ring_create*
  * @param	socket_id	Socket Id to allocate  mempool on.
  *
  * @return
@@ -253,7 +254,7 @@  typedef unsigned int (*cryptodev_asym_get_session_private_size_t)(
  *
  * @param	dev		Crypto device pointer
  * @param	xform		Single or chain of crypto xforms
- * @param	priv_sess	Pointer to cryptodev's private session structure
+ * @param	session		Pointer to cryptodev's private session structure
  * @param	mp		Mempool where the private session is allocated
  *
  * @return
@@ -271,7 +272,7 @@  typedef int (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev,
  *
  * @param	dev		Crypto device pointer
  * @param	xform		Single or chain of crypto xforms
- * @param	priv_sess	Pointer to cryptodev's private session structure
+ * @param	session		Pointer to cryptodev's private session structure
  * @param	mp		Mempool where the private session is allocated
  *
  * @return
@@ -333,7 +334,6 @@  typedef int (*cryptodev_sym_get_raw_dp_ctx_size_t)(struct rte_cryptodev *dev);
  *
  * @param	dev		Crypto device pointer.
  * @param	qp_id		Crypto device queue pair index.
- * @param	service_type	Type of the service requested.
  * @param	ctx		The raw data-path context data.
  * @param	sess_type	session type.
  * @param	session_ctx	Session context data. If NULL the driver
diff --git a/lib/librte_eal/include/rte_keepalive.h b/lib/librte_eal/include/rte_keepalive.h
index 4bda7ca56f..bd25508da8 100644
--- a/lib/librte_eal/include/rte_keepalive.h
+++ b/lib/librte_eal/include/rte_keepalive.h
@@ -52,7 +52,7 @@  typedef void (*rte_keepalive_failure_callback_t)(
  *  @param data Data pointer passed to rte_keepalive_register_relay_callback()
  *  @param id_core ID of the core for which state is being reported
  *  @param core_state The current state of the core
- *  @param Timestamp of when core was last seen alive
+ *  @param last_seen Timestamp of when core was last seen alive
  */
 typedef void (*rte_keepalive_relay_callback_t)(
 	void *data,
diff --git a/lib/librte_eventdev/rte_eventdev_pmd.h b/lib/librte_eventdev/rte_eventdev_pmd.h
index 27be376ed1..9e83993efa 100644
--- a/lib/librte_eventdev/rte_eventdev_pmd.h
+++ b/lib/librte_eventdev/rte_eventdev_pmd.h
@@ -297,7 +297,7 @@  typedef void (*eventdev_port_release_t)(void *port);
  *   Event device pointer
  * @param port
  *   Event port pointer
- * @param link
+ * @param queues
  *   Points to an array of *nb_links* event queues to be linked
  *   to the event port.
  * @param priorities
@@ -383,6 +383,10 @@  typedef void (*eventdev_dump_t)(struct rte_eventdev *dev, FILE *f);
  *
  * @param dev
  *   Event device pointer
+ * @param mode
+ *   Level (device, port or queue)
+ * @param queue_port_id
+ *   Queue or port number depending on mode
  * @param ids
  *   The stat ids to retrieve
  * @param values
@@ -410,8 +414,14 @@  typedef int (*eventdev_xstats_reset_t)(struct rte_eventdev *dev,
  *
  * @param dev
  *   Event device pointer
+ * @param mode
+ *   Level (device, port or queue)
+ * @param queue_port_id
+ *   Queue or port number depending on mode
  * @param xstats_names
  *   Array of name values to be filled in
+ * @param ids
+ *   The stat ids to retrieve
  * @param size
  *   Number of values in the xstats_names array
  * @return
diff --git a/lib/librte_port/rte_port.h b/lib/librte_port/rte_port.h
index 7f156ef47d..6b6a2cdd17 100644
--- a/lib/librte_port/rte_port.h
+++ b/lib/librte_port/rte_port.h
@@ -186,7 +186,7 @@  typedef int (*rte_port_out_op_tx)(
  */
 typedef int (*rte_port_out_op_tx_bulk)(
 	void *port,
-	struct rte_mbuf **pkt,
+	struct rte_mbuf **pkts,
 	uint64_t pkts_mask);
 
 /**
diff --git a/lib/librte_port/rte_swx_port.h b/lib/librte_port/rte_swx_port.h
index 4beb59991f..ecf109d2ca 100644
--- a/lib/librte_port/rte_swx_port.h
+++ b/lib/librte_port/rte_swx_port.h
@@ -50,7 +50,7 @@  typedef void *
 /**
  * Input port free
  *
- * @param[in] args
+ * @param[in] port
  *   Input port handle.
  */
 typedef void
@@ -129,7 +129,7 @@  typedef void *
 /**
  * Output port free
  *
- * @param[in] args
+ * @param[in] port
  *   Output port handle.
  */
 typedef void
diff --git a/lib/librte_rawdev/rte_rawdev_pmd.h b/lib/librte_rawdev/rte_rawdev_pmd.h
index 34dd7181b4..b1bed13ee2 100644
--- a/lib/librte_rawdev/rte_rawdev_pmd.h
+++ b/lib/librte_rawdev/rte_rawdev_pmd.h
@@ -155,6 +155,8 @@  typedef int (*rawdev_info_get_t)(struct rte_rawdev *dev,
  *   Raw device pointer
  * @param config
  *   Void object containing device specific configuration
+ * @param config_size
+ *   Size of the memory allocated for the configuration
  *
  * @return
  *   Returns 0 on success
@@ -214,6 +216,8 @@  typedef int (*rawdev_reset_t)(struct rte_rawdev *dev);
  *   Raw device queue index
  * @param[out] queue_conf
  *   Raw device queue configuration structure
+ * @param queue_conf_size
+ *   Size of the memory allocated for the configuration
  *
  * @return
  *   Returns 0 on success, negative errno on failure
@@ -232,6 +236,8 @@  typedef int (*rawdev_queue_conf_get_t)(struct rte_rawdev *dev,
  *   Rawqueue index
  * @param queue_conf
  *   Rawqueue configuration structure
+ * @param queue_conf_size
+ *   Size of the memory allocated for the configuration
  *
  * @return
  *   Returns 0 on success.
@@ -263,7 +269,7 @@  typedef int (*rawdev_queue_release_t)(struct rte_rawdev *dev,
  * This function helps in getting queue count supported, independently. It
  * can help in cases where iterator needs to be implemented.
  *
- * @param
+ * @param dev
  *   Raw device pointer
  * @return
  *   Number of queues; 0 is assumed to be a valid response.
@@ -279,7 +285,7 @@  typedef uint16_t (*rawdev_queue_count_t)(struct rte_rawdev *dev);
  *
  * @param dev
  *   Raw device pointer
- * @param bufs
+ * @param buffers
  *   array of buffers
  * @param count
  *   number of buffers passed
@@ -303,7 +309,7 @@  typedef int (*rawdev_enqueue_bufs_t)(struct rte_rawdev *dev,
  *
  * @param dev
  *   Raw device pointer
- * @param bufs
+ * @param buffers
  *   array of buffers
  * @param count
  *   Max buffers expected to be dequeued
@@ -444,7 +450,7 @@  typedef uint64_t (*rawdev_xstats_get_by_name_t)(const struct rte_rawdev *dev,
  *
  * @param dev
  *   Raw device pointer
- * @param status
+ * @param status_info
  *   void block containing device specific status information
  * @return
  *   0 for success,
@@ -472,8 +478,8 @@  typedef int (*rawdev_firmware_version_get_t)(struct rte_rawdev *dev,
  *
  * @param dev
  *   Raw device pointer
- * @param firmware_file
- *   file pointer to firmware area
+ * @param firmware_buf
+ *   Pointer to firmware image
  * @return
  *   >0, ~0: for successful load
  *   <0: for failure
diff --git a/lib/librte_security/rte_security_driver.h b/lib/librte_security/rte_security_driver.h
index c5abb07990..938373205c 100644
--- a/lib/librte_security/rte_security_driver.h
+++ b/lib/librte_security/rte_security_driver.h
@@ -41,7 +41,7 @@  typedef int (*security_session_create_t)(void *device,
 /**
  * Free driver private session data.
  *
- * @param	dev		Crypto/eth device pointer
+ * @param	device		Crypto/eth device pointer
  * @param	sess		Security session structure
  */
 typedef int (*security_session_destroy_t)(void *device,
@@ -95,16 +95,17 @@  int rte_security_dynfield_register(void);
 /**
  * Update the mbuf with provided metadata.
  *
+ * @param	device		Crypto/eth device pointer
  * @param	sess		Security session structure
  * @param	mb		Packet buffer
- * @param	mt		Metadata
+ * @param	params		Metadata
  *
  * @return
  *  - Returns 0 if metadata updated successfully.
  *  - Returns -ve value for errors.
  */
 typedef int (*security_set_pkt_metadata_t)(void *device,
-		struct rte_security_session *sess, struct rte_mbuf *m,
+		struct rte_security_session *sess, struct rte_mbuf *mb,
 		void *params);
 
 /**
diff --git a/lib/librte_table/rte_swx_table.h b/lib/librte_table/rte_swx_table.h
index dc434b72ef..5a3137ec53 100644
--- a/lib/librte_table/rte_swx_table.h
+++ b/lib/librte_table/rte_swx_table.h
@@ -127,12 +127,6 @@  typedef uint64_t
  * progress and it is passed as a parameter to the lookup operation. This allows
  * for multiple concurrent lookup operations into the same table.
  *
- * @param[in] params
- *   Table creation parameters.
- * @param[in] entries
- *   Entries to be added to the table at creation time.
- * @param[in] args
- *   Any additional table create arguments. It may be NULL.
  * @return
  *   Table memory footprint in bytes, on success, or zero, on error.
  */
diff --git a/lib/librte_table/rte_table.h b/lib/librte_table/rte_table.h
index cccded1a1c..096ab8a7c8 100644
--- a/lib/librte_table/rte_table.h
+++ b/lib/librte_table/rte_table.h
@@ -129,7 +129,7 @@  typedef int (*rte_table_op_entry_delete)(
  *
  * @param table
  *   Handle to lookup table instance
- * @param key
+ * @param keys
  *   Array containing lookup keys
  * @param entries
  *   Array containing data to be associated with each key. Every item in the
@@ -166,7 +166,7 @@  typedef int (*rte_table_op_entry_add_bulk)(
  *
  * @param table
  *   Handle to lookup table instance
- * @param key
+ * @param keys
  *   Array containing lookup keys
  * @param n_keys
  *   Number of keys to delete