[PATCH] dmaengine: shdma: correct most kernel-doc issues in shdma-base.h

[PATCH] dmaengine: shdma: correct most kernel-doc issues in shdma-base.h

[Randy Dunlap]

Fix kernel-doc comments in include/linux/shdma-base.h to avoid
most warnings:

- prefix an enum name with "enum"
- prefix enum values with '@'
- prefix struct member names with '@'

shdma-base.h:28: warning: cannot understand function prototype:
 'enum shdma_pm_state '
Warning: shdma-base.h:103 struct member 'desc_completed' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'halt_channel' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'channel_busy' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'slave_addr' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'desc_setup' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'set_slave' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'setup_xfer' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'start_xfer' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'embedded_desc' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'chan_irq' not described
 in 'shdma_ops'

This one is not fixed: from 4f46f8ac80416:
Warning: shdma-base.h:103 struct member 'get_partial' not described
 in 'shdma_ops'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
Cc: Paul Mundt <lethal@linux-sh.org>
Cc: Vinod Koul <vkoul@kernel.org>
Cc: dmaengine@vger.kernel.org
Cc: linux-sh@vger.kernel.org
---
 include/linux/shdma-base.h |   28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

--- linux-next-20251103.orig/include/linux/shdma-base.h
+++ linux-next-20251103/include/linux/shdma-base.h
@@ -19,11 +19,11 @@
 #include <linux/types.h>
 
 /**
- * shdma_pm_state - DMA channel PM state
- * SHDMA_PM_ESTABLISHED:	either idle or during data transfer
- * SHDMA_PM_BUSY:		during the transfer preparation, when we have to
+ * enum shdma_pm_state - DMA channel PM state
+ * @SHDMA_PM_ESTABLISHED:	either idle or during data transfer
+ * @SHDMA_PM_BUSY:		during the transfer preparation, when we have to
  *				drop the lock temporarily
- * SHDMA_PM_PENDING:	transfers pending
+ * @SHDMA_PM_PENDING:	transfers pending
  */
 enum shdma_pm_state {
 	SHDMA_PM_ESTABLISHED,
@@ -74,18 +74,18 @@ struct shdma_chan {
 
 /**
  * struct shdma_ops - simple DMA driver operations
- * desc_completed:	return true, if this is the descriptor, that just has
+ * @desc_completed:	return true, if this is the descriptor, that just has
  *			completed (atomic)
- * halt_channel:	stop DMA channel operation (atomic)
- * channel_busy:	return true, if the channel is busy (atomic)
- * slave_addr:		return slave DMA address
- * desc_setup:		set up the hardware specific descriptor portion (atomic)
- * set_slave:		bind channel to a slave
- * setup_xfer:		configure channel hardware for operation (atomic)
- * start_xfer:		start the DMA transfer (atomic)
- * embedded_desc:	return Nth struct shdma_desc pointer from the
+ * @halt_channel:	stop DMA channel operation (atomic)
+ * @channel_busy:	return true, if the channel is busy (atomic)
+ * @slave_addr:		return slave DMA address
+ * @desc_setup:		set up the hardware specific descriptor portion (atomic)
+ * @set_slave:		bind channel to a slave
+ * @setup_xfer:		configure channel hardware for operation (atomic)
+ * @start_xfer:		start the DMA transfer (atomic)
+ * @embedded_desc:	return Nth struct shdma_desc pointer from the
  *			descriptor array
- * chan_irq:		process channel IRQ, return true if a transfer has
+ * @chan_irq:		process channel IRQ, return true if a transfer has
  *			completed (atomic)
  */
 struct shdma_ops {