2024-05-31 07:21:38

by Yang Li

Subject: [PATCH -next] ntb: Fix kernel-doc param for ntb_transport_create_queue

The patch updates the function documentation comment for
ntb_transport_create_queue to adhere to the kernel-doc specification.

Signed-off-by: Yang Li <[email protected]>
---
drivers/ntb/ntb_transport.c | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/drivers/ntb/ntb_transport.c b/drivers/ntb/ntb_transport.c
index f9e7847a378e..5d466a3f117b 100644
--- a/drivers/ntb/ntb_transport.c
+++ b/drivers/ntb/ntb_transport.c
@@ -1966,9 +1966,10 @@ static bool ntb_dma_filter_fn(struct dma_chan *chan, void *node)

/**
* ntb_transport_create_queue - Create a new NTB transport layer queue
- * @rx_handler: receive callback function
- * @tx_handler: transmit callback function
- * @event_handler: event callback function
+ * @data: user-defined data to associate with the queue
+ * @client_dev: the device structure of the NTB client
+ * @handlers: structure containing receive, transmit, and event callback
+ * functions
*
* Create a new NTB transport layer queue and provide the queue with a callback
* routine for both transmit and receive. The receive callback routine will be
--
2.20.1.7.g153144c

2024-05-31 15:53:01

by Dave Jiang

Subject: Re: [PATCH -next] ntb: Fix kernel-doc param for ntb_transport_create_queue

On 5/31/24 12:21 AM, Yang Li wrote:
> The patch updates the function documentation comment for
> ntb_transport_create_queue to adhere to the kernel-doc specification.

I wouldn't say it's not adhering to kernel-doc specification but rather that it's documenting the incorrect/out of date parameters. So maybe something like:

Update ntb_transport_create_queue() kdoc header to specify the correct input parameters used by the function.
>
> Signed-off-by: Yang Li <[email protected]>

Besides the commit log change,
Reviewed-by: Dave Jiang <[email protected]>

> ---
> drivers/ntb/ntb_transport.c | 7 ++++---
> 1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/ntb/ntb_transport.c b/drivers/ntb/ntb_transport.c
> index f9e7847a378e..5d466a3f117b 100644
> --- a/drivers/ntb/ntb_transport.c
> +++ b/drivers/ntb/ntb_transport.c
> @@ -1966,9 +1966,10 @@ static bool ntb_dma_filter_fn(struct dma_chan *chan, void *node)
>
> /**
> * ntb_transport_create_queue - Create a new NTB transport layer queue
> - * @rx_handler: receive callback function
> - * @tx_handler: transmit callback function
> - * @event_handler: event callback function
> + * @data: user-defined data to associate with the queue
> + * @client_dev: the device structure of the NTB client
> + * @handlers: structure containing receive, transmit, and event callback
> + * functions
> *
> * Create a new NTB transport layer queue and provide the queue with a callback
> * routine for both transmit and receive. The receive callback routine will be