Re: [PATCH 1/3] net/mlx5: add missing function documentation
From: Adrien Mazarguil <hidden>
Date: 2018-02-16 14:26:45
I hate to sound pedantic but... On Thu, Feb 15, 2018 at 10:29:25AM +0100, Nelio Laranjeiro wrote:
quoted hunk ↗ jump to hunk
Signed-off-by: Nelio Laranjeiro <redacted> Acked-by: Yongseok Koh <redacted> --- drivers/net/mlx5/mlx5_trigger.c | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)diff --git a/drivers/net/mlx5/mlx5_trigger.c b/drivers/net/mlx5/mlx5_trigger.c index f5711a998..a70b13d52 100644 --- a/drivers/net/mlx5/mlx5_trigger.c +++ b/drivers/net/mlx5/mlx5_trigger.c@@ -14,6 +14,12 @@ #include "mlx5_rxtx.h" #include "mlx5_utils.h" +/** + * Stop traffic on Tx queues. + * + * @param priv
...there's an extra space between @param and priv :)
quoted hunk ↗ jump to hunk
+ * Pointer to private structure. + */ static void priv_txq_stop(struct priv *priv) {@@ -23,6 +29,15 @@ priv_txq_stop(struct priv *priv) mlx5_priv_txq_release(priv, i); } +/** + * Start traffic on Tx queues. + * + * @param priv
Ditto.
+ * Pointer to private structure. + * + * @return + * 0 on success, errno on error.
This should more accurately read "0 on success, positive errno value otherwise". I would suggest to document these functions only after the errno mess is sorted (patch 2/3 should come first) for a smaller amount of changes.
quoted hunk ↗ jump to hunk
+ */ static int priv_txq_start(struct priv *priv) {@@ -58,6 +73,12 @@ priv_txq_start(struct priv *priv) return ret; } +/** + * Stop traffic on Rx queues. + * + * @param priv
Extra space here also.
quoted hunk ↗ jump to hunk
+ * Pointer to private structure. + */ static void priv_rxq_stop(struct priv *priv) {@@ -67,6 +88,15 @@ priv_rxq_stop(struct priv *priv) mlx5_priv_rxq_release(priv, i); } +/** + * Start traffic on Rx queues. + * + * @param priv
Again.
+ * Pointer to private structure. + * + * @return + * 0 on success, errno on error.
Ditto regarding errno sign.
+ */
static int
priv_rxq_start(struct priv *priv)
{
--
2.11.0There are other functions are not properly documented either, you might want to add them for consistency: mlx5_ethdev.c: - mlx5_dev_supported_ptypes_get (no documentation) - mlx5_link_update_unlocked_gset (return value) - mlx5_link_update_unlocked_gs (return value) - priv_link_update (return value) - mlx5_link_update (return value) mlx5_flow.c: - mlx5_flow_create_eth (return value) - mlx5_flow_create_vlan (return value) - mlx5_flow_create_ipv4 (return value) - mlx5_flow_create_ipv6 (return value) - mlx5_flow_create_udp (return value) - mlx5_flow_create_tcp (return value) - mlx5_flow_create_vxlan (return value) - mlx5_flow_create_flag_mark (return value) - priv_flow_create_drop_queue (return in case of error) - priv_flow_verify (inconsistent @return syntax) mlx5_glue.c: - mlx5_glue_* (too many of them and those are basic wrappers, don't bother) mlx5_mr.c: - priv_mr_verify (inconsistent @return syntax) mlx5_rxq.c: - mlx5_priv_rxq_ibv_verify (ditto) - mlx5_priv_rxq_verify (ditto) - mlx5_priv_ind_table_ibv_verify (ditto) - mlx5_priv_hrxq_ibv_verify (ditto) mlx5_rxtx.c: - mlx5_tx_burst_raw_vec - mlx5_tx_burst_vec - mlx5_rx_burst_vec - priv_check_raw_vec_tx_support - priv_check_vec_tx_support - rxq_check_vec_support - priv_check_vec_rx_support mlx5_trigger.c: - Those are taken care of by the current patch. mlx5_txq.c: - mlx5_priv_txq_ibv_verify (inconsistent @return syntax) - mlx5_priv_txq_verify (ditto) mlx5_vlan.c - mlx5_vlan_offload_set (return value) I think that's all. -- Adrien Mazarguil 6WIND