From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 47CB6CCF9E9 for ; Sun, 26 Oct 2025 22:46:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:List-Subscribe:List-Help :List-Post:List-Archive:List-Unsubscribe:List-Id:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=rCRAutHedepxoaqlhY+trKzO9H8TOhlVc7iMT1F8fAg=; b=g5Vo1ml+G422vQF74vmP7a1ADv oxZ1zE/JAjYNbUv2Lvhuc1K15NsOcQX9POme/Gu4+qfrk9vq50uFo9PycS7AS29H7dfl3rU5QKEhu uxxQOy0RwLsushei9wi3sqB+llU4088KcPvVTZ/gInBRrFXyrGuRw8AmJx5EvRJRMK6DsqtAbTO5f YGCBtK15QgFByYn//ALIumTtFuG06DFMX3rZx743mUgPXfqlFWy8Bl8NPUza+hrmZKJabNiGvg6kL aJ/qw+S6b+SAR02BVo5TGTfnWiG55Gt49DA5+NvBGdu0s0MYDKS3h42nK36flApeqffhU3+Dv5jJd ees2I3yw==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.98.2 #2 (Red Hat Linux)) id 1vD9Ux-0000000CpPQ-1ONq; Sun, 26 Oct 2025 22:46:03 +0000 Received: from [50.53.43.113] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1vD9Uu-0000000CpNa-25U1; Sun, 26 Oct 2025 22:46:00 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Chunfeng Yun , linux-arm-kernel@lists.infradead.org, linux-mediatek@lists.infradead.org, Matthias Brugger , AngeloGioacchino Del Regno , Greg Kroah-Hartman , Mauro Carvalho Chehab , linux-usb@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 2/2] usb: mtu3: fix invalid kernel-doc in mtu3.h Date: Sun, 26 Oct 2025 15:45:58 -0700 Message-ID: <20251026224558.826143-2-rdunlap@infradead.org> X-Mailer: git-send-email 2.51.1 In-Reply-To: <20251026224558.826143-1-rdunlap@infradead.org> References: <20251026224558.826143-1-rdunlap@infradead.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: linux-mediatek@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "Linux-mediatek" Errors-To: linux-mediatek-bounces+linux-mediatek=archiver.kernel.org@lists.infradead.org Fix unconventional kernel-doc lines to avoid warnings. Summary of changes: - change non-kernel-doc comments from "/**" to "/*" - add "enum - short description" for undescribed enums - use leading '@' for describing enum members and struct members - add "struct - 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 --- Cc: Chunfeng Yun Cc: linux-arm-kernel@lists.infradead.org Cc: linux-mediatek@lists.infradead.org Cc: Matthias Brugger Cc: AngeloGioacchino Del Regno Cc: Greg Kroah-Hartman Cc: Mauro Carvalho Chehab 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) */