[PATCH v2] async_tx: fix kernel-doc notation warnings

[PATCH v2] async_tx: fix kernel-doc notation warnings

[Randy Dunlap]

Fix kernel-doc warnings by adding "struct" keyword or "enum" keyword.
Also fix 2 function parameter descriptions.
Change some functions and structs from kernel-doc /** notation
to regular /* comment notation.

async_pq.c:18: warning: cannot understand function prototype: 'struct page *pq_scribble_page; '
async_pq.c:18: error: Cannot parse struct or union!
async_pq.c:40: warning: No description found for return value of 'do_async_gen_syndrome'
async_pq.c:109: warning: Function parameter or member 'blocks' not described in 'do_sync_gen_syndrome'
async_pq.c:109: warning: Function parameter or member 'offsets' not described in 'do_sync_gen_syndrome'
async_pq.c:109: warning: Function parameter or member 'disks' not described in 'do_sync_gen_syndrome'
async_pq.c:109: warning: Function parameter or member 'len' not described in 'do_sync_gen_syndrome'
async_pq.c:109: warning: Function parameter or member 'submit' not described in 'do_sync_gen_syndrome'

async_tx.c:136: warning: cannot understand function prototype: 'enum submit_disposition '
async_tx.c:264: warning: Function parameter or member 'tx' not described in 'async_tx_quiesce'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: linux-crypto@vger.kernel.org
---
v2: fix more warnings

 crypto/async_tx/async_pq.c |   10 +++++-----
 crypto/async_tx/async_tx.c |    4 ++--
 2 files changed, 7 insertions(+), 7 deletions(-)

diff -- a/crypto/async_tx/async_pq.c b/crypto/async_tx/async_pq.c
--- a/crypto/async_tx/async_pq.c
+++ b/crypto/async_tx/async_pq.c
@@ -11,8 +11,8 @@
 #include <linux/async_tx.h>
 #include <linux/gfp.h>
 
-/**
- * pq_scribble_page - space to hold throwaway P or Q buffer for
+/*
+ * struct pq_scribble_page - space to hold throwaway P or Q buffer for
  * synchronous gen_syndrome
  */
 static struct page *pq_scribble_page;
@@ -28,7 +28,7 @@ static struct page *pq_scribble_page;
 
 #define MAX_DISKS 255
 
-/**
+/*
  * do_async_gen_syndrome - asynchronously calculate P and/or Q
  */
 static __async_inline struct dma_async_tx_descriptor *
@@ -100,7 +100,7 @@ do_async_gen_syndrome(struct dma_chan *c
 	return tx;
 }
 
-/**
+/*
  * do_sync_gen_syndrome - synchronously calculate a raid6 syndrome
  */
 static void
@@ -281,7 +281,7 @@ pq_val_chan(struct async_submit_ctl *sub
 /**
  * async_syndrome_val - asynchronously validate a raid6 syndrome
  * @blocks: source blocks from idx 0..disks-3, P @ disks-2 and Q @ disks-1
- * @offset: common offset into each block (src and dest) to start transaction
+ * @offsets: common offset into each block (src and dest) to start transaction
  * @disks: number of blocks (including missing P or Q, see below)
  * @len: length of operation in bytes
  * @pqres: on val failure SUM_CHECK_P_RESULT and/or SUM_CHECK_Q_RESULT are set
diff -- a/crypto/async_tx/async_tx.c b/crypto/async_tx/async_tx.c
--- a/crypto/async_tx/async_tx.c
+++ b/crypto/async_tx/async_tx.c
@@ -124,7 +124,7 @@ async_tx_channel_switch(struct dma_async
 
 
 /**
- * submit_disposition - flags for routing an incoming operation
+ * enum submit_disposition - flags for routing an incoming operation
  * @ASYNC_TX_SUBMITTED: we were able to append the new operation under the lock
  * @ASYNC_TX_CHANNEL_SWITCH: when the lock is dropped schedule a channel switch
  * @ASYNC_TX_DIRECT_SUBMIT: when the lock is dropped submit directly
@@ -258,7 +258,7 @@ EXPORT_SYMBOL_GPL(async_trigger_callback
 
 /**
  * async_tx_quiesce - ensure tx is complete and freeable upon return
- * @tx - transaction to quiesce
+ * @tx: transaction to quiesce
  */
 void async_tx_quiesce(struct dma_async_tx_descriptor **tx)
 {

RE: [PATCH v2] async_tx: fix kernel-doc notation warnings

[Dan Williams]

Randy Dunlap wrote:
> Fix kernel-doc warnings by adding "struct" keyword or "enum" keyword.
> Also fix 2 function parameter descriptions.
> Change some functions and structs from kernel-doc /** notation
> to regular /* comment notation.
> 
> async_pq.c:18: warning: cannot understand function prototype: 'struct page *pq_scribble_page; '
> async_pq.c:18: error: Cannot parse struct or union!
> async_pq.c:40: warning: No description found for return value of 'do_async_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'blocks' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'offsets' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'disks' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'len' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'submit' not described in 'do_sync_gen_syndrome'
> 
> async_tx.c:136: warning: cannot understand function prototype: 'enum submit_disposition '
> async_tx.c:264: warning: Function parameter or member 'tx' not described in 'async_tx_quiesce'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Herbert Xu <herbert@gondor.apana.org.au>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: linux-crypto@vger.kernel.org
> ---
> v2: fix more warnings

Looks good to me.

Reviewed-by: Dan Williams <dan.j.williams@intel.com>

Herbert, can you pick this up?

Re: [PATCH v2] async_tx: fix kernel-doc notation warnings

[Herbert Xu]

On Wed, Mar 15, 2023 at 04:35:22PM -0700, Dan Williams wrote:
>
> Looks good to me.
> 
> Reviewed-by: Dan Williams <dan.j.williams@intel.com>
> 
> Herbert, can you pick this up?

Sure will do.  Thanks for fixing this up, I think these might be
the last warnings under the crypto directory :)

Cheers,
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt

Re: [PATCH v2] async_tx: fix kernel-doc notation warnings

[Herbert Xu]

On Mon, Mar 13, 2023 at 07:47:34PM -0700, Randy Dunlap wrote:
> Fix kernel-doc warnings by adding "struct" keyword or "enum" keyword.
> Also fix 2 function parameter descriptions.
> Change some functions and structs from kernel-doc /** notation
> to regular /* comment notation.
> 
> async_pq.c:18: warning: cannot understand function prototype: 'struct page *pq_scribble_page; '
> async_pq.c:18: error: Cannot parse struct or union!
> async_pq.c:40: warning: No description found for return value of 'do_async_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'blocks' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'offsets' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'disks' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'len' not described in 'do_sync_gen_syndrome'
> async_pq.c:109: warning: Function parameter or member 'submit' not described in 'do_sync_gen_syndrome'
> 
> async_tx.c:136: warning: cannot understand function prototype: 'enum submit_disposition '
> async_tx.c:264: warning: Function parameter or member 'tx' not described in 'async_tx_quiesce'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Herbert Xu <herbert@gondor.apana.org.au>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: linux-crypto@vger.kernel.org
> ---
> v2: fix more warnings
> 
>  crypto/async_tx/async_pq.c |   10 +++++-----
>  crypto/async_tx/async_tx.c |    4 ++--
>  2 files changed, 7 insertions(+), 7 deletions(-)

Patch applied.  Thanks.
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt