mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2026-09-22 09:34:56 +02:00
Randy Dunlap
bf3371dfe3
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>
Linux kernel
============
There are several guides for kernel developers and users. These guides can
be rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.
In order to build the documentation, use ``make htmldocs`` or
``make pdfdocs``. The formatted documentation can also be read online at:
https://www.kernel.org/doc/html/latest/
There are various text files in the Documentation/ subdirectory,
several of them using the reStructuredText markup notation.
Please read the Documentation/process/changes.rst file, as it contains the
requirements for building and running the kernel, and information about
the problems which may result by upgrading your kernel.