[PATCH] usb: xhci-mtk: correct most kernel-doc problems in xhci-mtk.h

[Randy Dunlap]

Correct the kernel-doc notation in xhck-mtk.h to avoid most kernel-doc
warnings. Summary of changes:

- don't use /** to begin comments that are not in kernel-doc format
- add missing "struct mu3h_sch_tt" kernel-doc line
- convert several "struct mu3h_...:" to using " - " to separate the
  struct name from its short description
- add a missing @speed: struct member description

Warning messages that are fixed:

xhci-mtk.h:25: warning: This comment starts with '/**', but isn't a
 kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * To simplify scheduler algorithm, set a upper limit for ESIT,
xhci-mtk.h:25: warning: missing initial short description on line:
 * To simplify scheduler algorithm, set a upper limit for ESIT,

Warning: drivers/usb/host/xhci-mtk.h:36 Cannot find identifier on line:
 * @fs_bus_bw_out: save bandwidth used by FS/LS OUT eps in each uframes
Warning: drivers/usb/host/xhci-mtk.h:37 Cannot find identifier on line:
 * @fs_bus_bw_in: save bandwidth used by FS/LS IN eps in each uframes
Warning: drivers/usb/host/xhci-mtk.h:38 Cannot find identifier on line:
 * @ls_bus_bw: save bandwidth used by LS eps in each uframes
Warning: drivers/usb/host/xhci-mtk.h:39 Cannot find identifier on line:
 * @fs_frame_bw: save bandwidth used by FS/LS eps in each FS frames
Warning: drivers/usb/host/xhci-mtk.h:40 Cannot find identifier on line:
 * @in_ss_cnt: the count of Start-Split for IN eps
Warning: drivers/usb/host/xhci-mtk.h:41 Cannot find identifier on line:
 * @ep_list: Endpoints using this TT
Warning: drivers/usb/host/xhci-mtk.h:42 Cannot find identifier on line:
 */
Warning: drivers/usb/host/xhci-mtk.h:43 Cannot find identifier on line:
struct mu3h_sch_tt {
Warning: drivers/usb/host/xhci-mtk.h:44 Cannot find identifier on line:
        u16 fs_bus_bw_out[XHCI_MTK_MAX_ESIT];
Warning: drivers/usb/host/xhci-mtk.h:45 Cannot find identifier on line:
        u16 fs_bus_bw_in[XHCI_MTK_MAX_ESIT];
Warning: drivers/usb/host/xhci-mtk.h:46 Cannot find identifier on line:
        u8 ls_bus_bw[XHCI_MTK_MAX_ESIT];
Warning: drivers/usb/host/xhci-mtk.h:47 Cannot find identifier on line:
        u16 fs_frame_bw[XHCI_MTK_FRAMES_CNT];
Warning: drivers/usb/host/xhci-mtk.h:48 Cannot find identifier on line:
        u8 in_ss_cnt[XHCI_MTK_MAX_ESIT];
Warning: drivers/usb/host/xhci-mtk.h:49 Cannot find identifier on line:
        struct list_head ep_list;
Warning: drivers/usb/host/xhci-mtk.h:50 Cannot find identifier on line:
};
Warning: drivers/usb/host/xhci-mtk.h:51 Cannot find identifier on line:

Warning: drivers/usb/host/xhci-mtk.h:52 Cannot find identifier on line:
/**
Warning: drivers/usb/host/xhci-mtk.h:121 struct member 'speed' not
 described in 'mu3h_sch_ep_info'

Signed-off-by: Randy Dunlap <rdunlap at infradead.org>
---

This leaves 12 warnings (below) due to not using valid kernel-doc.
I can fix these as well if you would like for me to do that.

Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_ctr0' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_ctr1' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_ctr2' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_ctr3' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_sts1' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'ip_pw_sts2' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'reserved0' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'reserved1' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'u3_ctrl_p' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'u2_ctrl_p' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'reserved2' not described in 'mu3c_ippc_regs'
Warning: drivers/usb/host/xhci-mtk.h:150 struct member 'reserved3' not described in 'mu3c_ippc_regs'

---
Cc: Chunfeng Yun <chunfeng.yun at mediatek.com>
Cc: Greg Kroah-Hartman <gregkh at linuxfoundation.org>
Cc: linux-usb at vger.kernel.org
Cc: linux-arm-kernel at lists.infradead.org
Cc: linux-mediatek at lists.infradead.org
---
 drivers/usb/host/xhci-mtk.h |   10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

--- linux-next-20251103.orig/drivers/usb/host/xhci-mtk.h
+++ linux-next-20251103/drivers/usb/host/xhci-mtk.h
@@ -21,7 +21,7 @@
 /* support at most 64 ep, use 32 size hash table */
 #define SCH_EP_HASH_BITS	5
 
-/**
+/*
  * To simplify scheduler algorithm, set a upper limit for ESIT,
  * if a synchromous ep's ESIT is larger than @XHCI_MTK_MAX_ESIT,
  * round down to the limit value, that means allocating more
@@ -34,6 +34,7 @@
 #define XHCI_MTK_FRAMES_CNT	(XHCI_MTK_MAX_ESIT / UFRAMES_PER_FRAME)
 
 /**
+ * struct mu3h_sch_tt - TT scheduling data
  * @fs_bus_bw_out: save bandwidth used by FS/LS OUT eps in each uframes
  * @fs_bus_bw_in: save bandwidth used by FS/LS IN eps in each uframes
  * @ls_bus_bw: save bandwidth used by LS eps in each uframes
@@ -51,7 +52,7 @@ struct mu3h_sch_tt {
 };
 
 /**
- * struct mu3h_sch_bw_info: schedule information for bandwidth domain
+ * struct mu3h_sch_bw_info - schedule information for bandwidth domain
  *
  * @bus_bw: array to keep track of bandwidth already used at each uframes
  *
@@ -63,7 +64,7 @@ struct mu3h_sch_bw_info {
 };
 
 /**
- * struct mu3h_sch_ep_info: schedule information for endpoint
+ * struct mu3h_sch_ep_info - schedule information for endpoint
  *
  * @esit: unit is 125us, equal to 2 << Interval field in ep-context
  * @num_esit: number of @esit in a period
@@ -77,6 +78,7 @@ struct mu3h_sch_bw_info {
  * @ep_type: endpoint type
  * @maxpkt: max packet size of endpoint
  * @ep: address of usb_host_endpoint struct
+ * @speed: usb device speed
  * @allocated: the bandwidth is aready allocated from bus_bw
  * @offset: which uframe of the interval that transfer should be
  *		scheduled first time within the interval
@@ -125,7 +127,7 @@ struct mu3h_sch_ep_info {
 #define MU3C_U2_PORT_MAX 5
 
 /**
- * struct mu3c_ippc_regs: MTK ssusb ip port control registers
+ * struct mu3c_ippc_regs - MTK ssusb ip port control registers
  * @ip_pw_ctr0~3: ip power and clock control registers
  * @ip_pw_sts1~2: ip power and clock status registers
  * @ip_xhci_cap: ip xHCI capability register