[PATCH 08/30] usb: gadget: udc: core: Fix a bunch of kerneldoc misdemeanours

From: Lee Jones
Date: Fri Jul 03 2020 - 13:42:21 EST


Firstly, file headers should not be in kerneldoc format. Function
args should be in the format '@.*: '. We also take the time to
add some descriptions for various argument which have been
previously left out. Finally we remove descriptions for absent
arguments.

Fixes the following W=1 kernel build warning(s):

drivers/usb/gadget/udc/core.c:25: warning: Incorrect use of kernel-doc format: * struct usb_udc - describes one usb device controller
drivers/usb/gadget/udc/core.c:36: warning: cannot understand function prototype: 'struct usb_udc '
drivers/usb/gadget/udc/core.c:901: warning: Function parameter or member 'ep' not described in 'usb_gadget_giveback_request'
drivers/usb/gadget/udc/core.c:901: warning: Function parameter or member 'req' not described in 'usb_gadget_giveback_request'
drivers/usb/gadget/udc/core.c:1098: warning: Function parameter or member 'udc' not described in 'usb_gadget_udc_stop'
drivers/usb/gadget/udc/core.c:1098: warning: Excess function parameter 'gadget' description in 'usb_gadget_udc_stop'
drivers/usb/gadget/udc/core.c:1098: warning: Excess function parameter 'driver' description in 'usb_gadget_udc_stop'

Cc: Felipe Balbi <balbi@xxxxxxxxxx>
Signed-off-by: Lee Jones <lee.jones@xxxxxxxxxx>
---
drivers/usb/gadget/udc/core.c | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/drivers/usb/gadget/udc/core.c b/drivers/usb/gadget/udc/core.c
index 2e28dde8376f6..16790c02a530c 100644
--- a/drivers/usb/gadget/udc/core.c
+++ b/drivers/usb/gadget/udc/core.c
@@ -1,5 +1,5 @@
// SPDX-License-Identifier: GPL-2.0
-/**
+/*
* udc.c - Core UDC Framework
*
* Copyright (C) 2010 Texas Instruments
@@ -23,11 +23,11 @@

/**
* struct usb_udc - describes one usb device controller
- * @driver - the gadget driver pointer. For use by the class code
- * @dev - the child device to the actual controller
- * @gadget - the gadget. For use by the class code
- * @list - for use by the udc class driver
- * @vbus - for udcs who care about vbus status, this value is real vbus status;
+ * @driver: the gadget driver pointer. For use by the class code
+ * @dev: the child device to the actual controller
+ * @gadget: the gadget. For use by the class code
+ * @list: for use by the udc class driver
+ * @vbus: for udcs who care about vbus status, this value is real vbus status;
* for udcs who do not care about vbus status, this value is always true
*
* This represents the internal data structure which is used by the UDC-class
@@ -891,6 +891,9 @@ EXPORT_SYMBOL_GPL(usb_gadget_unmap_request);

/**
* usb_gadget_giveback_request - give the request back to the gadget layer
+ * @ep: the endpoint to be used with with the request
+ * @req: the request being given back
+ *
* Context: in_interrupt()
*
* This is called by device controller drivers in order to return the
@@ -1084,8 +1087,7 @@ static inline int usb_gadget_udc_start(struct usb_udc *udc)

/**
* usb_gadget_udc_stop - tells usb device controller we don't need it anymore
- * @gadget: The device we want to stop activity
- * @driver: The driver to unbind from @gadget
+ * @udc: The UDC to be stopped
*
* This call is issued by the UDC Class driver after calling
* gadget driver's unbind() method.
--
2.25.1