[PATCH 1/2] usb: mtu3: fix misspelled words

[PATCH 1/2] usb: mtu3: fix misspelled words

[Randy Dunlap]

Fix spelling errors as reported by codespell.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Chunfeng Yun <chunfeng.yun@mediatek.com>
Cc: linux-arm-kernel@lists.infradead.org
Cc: linux-mediatek@lists.infradead.org
Cc: Matthias Brugger <matthias.bgg@gmail.com>
Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-usb@vger.kernel.org
Cc: linux-doc@vger.kernel.org
---
 drivers/usb/mtu3/mtu3.h      |    4 ++--
 drivers/usb/mtu3/mtu3_core.c |    2 +-
 drivers/usb/mtu3/mtu3_qmu.c  |    2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

--- linux-next.orig/drivers/usb/mtu3/mtu3_core.c
+++ linux-next/drivers/usb/mtu3/mtu3_core.c
@@ -290,7 +290,7 @@ static void mtu3_csr_init(struct mtu3 *m
 
 	/* delay about 0.1us from detecting reset to send chirp-K */
 	mtu3_clrbits(mbase, U3D_LINK_RESET_INFO, WTCHRP_MSK);
-	/* enable automatical HWRW from L1 */
+	/* enable automatic HWRW from L1 */
 	mtu3_setbits(mbase, U3D_POWER_MANAGEMENT, LPM_HRWE);
 }
 
--- linux-next.orig/drivers/usb/mtu3/mtu3.h
+++ linux-next/drivers/usb/mtu3/mtu3.h
@@ -76,7 +76,7 @@ struct mtu3_request;
 
 /**
  * Normally the device works on HS or SS, to simplify fifo management,
- * devide fifo into some 512B parts, use bitmap to manage it; And
+ * 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
  * up to 64KB fifo size.
  * NOTE: MTU3_EP_FIFO_UNIT should be power of two
@@ -121,7 +121,7 @@ enum mtu3_g_ep0_state {
 };
 
 /**
- * MTU3_DR_FORCE_NONE: automatically switch host and periperal 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
  *		IDPIN signal.
--- linux-next.orig/drivers/usb/mtu3/mtu3_qmu.c
+++ linux-next/drivers/usb/mtu3/mtu3_qmu.c
@@ -221,7 +221,7 @@ static struct qmu_gpd *advance_deq_gpd(s
 	return ring->dequeue;
 }
 
-/* check if a ring is emtpy */
+/* check if a ring is empty */
 static bool gpd_ring_empty(struct mtu3_gpd_ring *ring)
 {
 	struct qmu_gpd *enq = ring->enqueue;

[PATCH 2/2] usb: mtu3: fix invalid kernel-doc in mtu3.h

[Randy Dunlap]

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>
---
Cc: Chunfeng Yun <chunfeng.yun@mediatek.com>
Cc: linux-arm-kernel@lists.infradead.org
Cc: linux-mediatek@lists.infradead.org
Cc: Matthias Brugger <matthias.bgg@gmail.com>
Cc: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-usb@vger.kernel.org
Cc: linux-doc@vger.kernel.org
---
 drivers/usb/mtu3/mtu3.h |   32 ++++++++++++++++++++------------
 1 file changed, 20 insertions(+), 12 deletions(-)

--- linux-next.orig/drivers/usb/mtu3/mtu3.h
+++ linux-next/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)
  */