usb: mtu3: fix invalid kernel-doc in mtu3.h

Fix unconventional kernel-doc lines to avoid warnings.
Summary of changes:

- change non-kernel-doc comments from "/**" to "/*"
- add "enum <enum-name> - short description" for undescribed enums
- use leading '@' for describing enum members and struct members
- add "struct <struct-name> - short description" for undescribed structs

Repair and remove invalid or unconventional lines in mtu3.h:

(This list is a combination of warnings from the old kernel-doc.pl and
the new kernel-doc.py scripts. This combo provides better coverage
of all problems.)

mtu3.h:69: warning: This comment starts with '/**', but isn't a
 kernel-doc comment.
 * IP TRUNK version
mtu3.h:69: warning: missing initial short description on line:
 * IP TRUNK version
mtu3.h:78: warning: This comment starts with '/**', but isn't a
 kernel-doc comment.
 * Normally the device works on HS or SS, to simplify fifo management,
mtu3.h:78: warning: missing initial short description on line:
 * Normally the device works on HS or SS, to simplify fifo management,
mtu3.h:89: warning: This comment starts with '/**', but isn't
 a kernel-doc comment.
 * Maximum size of ep0 response buffer for ch9 requests,
mtu3.h:89: warning: missing initial short description on line:
 * Maximum size of ep0 response buffer for ch9 requests,
mtu3.h:106: warning: Cannot understand  * @MU3D_EP0_STATE_SETUP: waits for
 SETUP or received a SETUP
 on line 106 - I thought it was a doc line
mtu3.h:130: warning: cannot understand function prototype:
 'enum mtu3_dr_force_mode'
mtu3.h:137: warning: Cannot understand  * @base: the base address of fifo
 on line 137 - I thought it was a doc line
mtu3.h:148: warning: missing initial short description on line:
 * General Purpose Descriptor (GPD):
mtu3.h:174: warning: cannot understand function prototype:
 'struct qmu_gpd'
mtu3.h:189: warning: cannot understand function prototype:
 'struct mtu3_gpd_ring'
mtu3.h:198: warning: Cannot understand * @vbus: vbus 5V used by host mode
 on line 198 - I thought it was a doc line
mtu3.h:225: warning: Cannot understand  * @mac_base: register base address
 of device MAC, exclude xHCI's
 on line 225 - I thought it was a doc line
mtu3.h:275: warning: cannot understand function prototype: 'struct mtu3_ep'

Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_NONE'
 not described in enum 'mtu3_dr_force_mode'
Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_HOST'
 not described in enum 'mtu3_dr_force_mode'
Warning: drivers/usb/mtu3/mtu3.h:135 Enum value 'MTU3_DR_FORCE_DEVICE'
 not described in enum 'mtu3_dr_force_mode'
Warning: drivers/usb/mtu3/mtu3.h:270 Cannot find identifier on line:
 * @fifo_size: it is (@slot + 1) * @fifo_seg_size
Warning: drivers/usb/mtu3/mtu3.h:271 Cannot find identifier on line:
 * @fifo_seg_size: it is roundup_pow_of_two(@maxp)
Warning: drivers/usb/mtu3/mtu3.h:272 Cannot find identifier on line:
 */
Warning: drivers/usb/mtu3/mtu3.h:273 Cannot find identifier on line:
struct mtu3_ep {
Warning: drivers/usb/mtu3/mtu3.h:274 Cannot find identifier on line:
        struct usb_ep ep;
Warning: drivers/usb/mtu3/mtu3.h:275 Cannot find identifier on line:
        char name[12];
Warning: drivers/usb/mtu3/mtu3.h:276 missing initial short description
 on line:
        struct mtu3 *mtu;

This removes all of the invalid/unconventional kernel-doc attempts but
still leaves quite a few struct members in structs ssusb_mtk, mtu3_ep,
and mtu3 without kernel-doc descriptions.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://patch.msgid.link/20251026224558.826143-2-rdunlap@infradead.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

1 files changed, 20 insertions, 12 deletions

diff --git a/drivers/usb/mtu3/mtu3.h b/drivers/usb/mtu3/mtu3.h
index 5e59f58940b5..ba5a63669e5f 100644
--- a/drivers/usb/mtu3/mtu3.h
+++ b/drivers/usb/mtu3/mtu3.h
@@ -65,7 +65,7 @@ struct mtu3_request;
 #define MTU3_U3_IP_SLOT_DEFAULT 2
 #define MTU3_U2_IP_SLOT_DEFAULT 1
 
-/**
+/*
  * IP TRUNK version
  * from 0x1003 version, USB3 Gen2 is supported, two changes affect driver:
  * 1. MAXPKT and MULTI bits layout of TXCSR1 and RXCSR1 are adjusted,
@@ -74,7 +74,7 @@ struct mtu3_request;
  */
 #define MTU3_TRUNK_VERS_1003	0x1003
 
-/**
+/*
  * Normally the device works on HS or SS, to simplify fifo management,
  * divide fifo into some 512B parts, use bitmap to manage it; And
  * 128 bits size of bitmap is large enough, that means it can manage
@@ -85,7 +85,7 @@ struct mtu3_request;
 #define MTU3_FIFO_BIT_SIZE		128
 #define MTU3_U2_IP_EP0_FIFO_SIZE	64
 
-/**
+/*
  * Maximum size of ep0 response buffer for ch9 requests,
  * the SET_SEL request uses 6 so far, and GET_STATUS is 2
  */
@@ -103,6 +103,7 @@ enum mtu3_speed {
 };
 
 /**
+ * enum mtu3_g_ep0_state - endpoint 0 states
  * @MU3D_EP0_STATE_SETUP: waits for SETUP or received a SETUP
  *		without data stage.
  * @MU3D_EP0_STATE_TX: IN data stage
@@ -121,11 +122,12 @@ enum mtu3_g_ep0_state {
 };
 
 /**
- * MTU3_DR_FORCE_NONE: automatically switch host and peripheral mode
+ * enum mtu3_dr_force_mode - indicates host/OTG operating mode
+ * @MTU3_DR_FORCE_NONE: automatically switch host and peripheral mode
  *		by IDPIN signal.
- * MTU3_DR_FORCE_HOST: force to enter host mode and override OTG
+ * @MTU3_DR_FORCE_HOST: force to enter host mode and override OTG
  *		IDPIN signal.
- * MTU3_DR_FORCE_DEVICE: force to enter peripheral mode.
+ * @MTU3_DR_FORCE_DEVICE: force to enter peripheral mode.
  */
 enum mtu3_dr_force_mode {
 	MTU3_DR_FORCE_NONE = 0,
@@ -134,6 +136,7 @@ enum mtu3_dr_force_mode {
 };
 
 /**
+ * struct mtu3_fifo_info - HW FIFO description and management data
  * @base: the base address of fifo
  * @limit: the bitmap size in bits
  * @bitmap: fifo bitmap in unit of @MTU3_EP_FIFO_UNIT
@@ -145,7 +148,7 @@ struct mtu3_fifo_info {
 };
 
 /**
- * General Purpose Descriptor (GPD):
+ * struct qmu_gpd - General Purpose Descriptor (GPD):
  *	The format of TX GPD is a little different from RX one.
  *	And the size of GPD is 16 bytes.
  *
@@ -179,11 +182,13 @@ struct qmu_gpd {
 } __packed;
 
 /**
-* dma: physical base address of GPD segment
-* start: virtual base address of GPD segment
-* end: the last GPD element
-* enqueue: the first empty GPD to use
-* dequeue: the first completed GPD serviced by ISR
+* struct mtu3_gpd_ring - GPD ring descriptor
+* @dma: physical base address of GPD segment
+* @start: virtual base address of GPD segment
+* @end: the last GPD element
+* @enqueue: the first empty GPD to use
+* @dequeue: the first completed GPD serviced by ISR
+*
 * NOTE: the size of GPD ring should be >= 2
 */
 struct mtu3_gpd_ring {
@@ -195,6 +200,7 @@ struct mtu3_gpd_ring {
 };
 
 /**
+* struct otg_switch_mtk - OTG/dual-role switch management
 * @vbus: vbus 5V used by host mode
 * @edev: external connector used to detect vbus and iddig changes
 * @id_nb : notifier for iddig(idpin) detection
@@ -222,6 +228,7 @@ struct otg_switch_mtk {
 };
 
 /**
+ * struct ssusb_mtk - SuperSpeed USB descriptor (MTK)
  * @mac_base: register base address of device MAC, exclude xHCI's
  * @ippc_base: register base address of IP Power and Clock interface (IPPC)
  * @vusb33: usb3.3V shared by device/host IP
@@ -268,6 +275,7 @@ struct ssusb_mtk {
 };
 
 /**
+ * struct mtu3_ep - common mtu3 endpoint description
  * @fifo_size: it is (@slot + 1) * @fifo_seg_size
  * @fifo_seg_size: it is roundup_pow_of_two(@maxp)
  */