Message-ID: <20250111063230.910945-1-rdunlap@infradead.org>
Date: Fri, 10 Jan 2025 22:32:30 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: linux-kernel@...r.kernel.org
Cc: Randy Dunlap <rdunlap@...radead.org>,
	Maxim Levitsky <maximlevitsky@...il.com>,
	Alex Dubov <oakad@...oo.com>,
	Ulf Hansson <ulf.hansson@...aro.org>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	linux-mmc@...r.kernel.org
Subject: [PATCH] memstick: core: fix kernel-doc notation

Use the correct kernel-doc format for function parameters (':'
instead of '-') to eliminate kernel-doc warnings.
Add some "Returns:" notations to functions.

memstick.c:206: warning: Function parameter or struct member 'host' not described in 'memstick_detect_change'
memstick.c:222: warning: Function parameter or struct member 'host' not described in 'memstick_next_req'
memstick.c:222: warning: Function parameter or struct member 'mrq' not described in 'memstick_next_req'
memstick.c:248: warning: Function parameter or struct member 'host' not described in 'memstick_new_req'
memstick.c:265: warning: Function parameter or struct member 'mrq' not described in 'memstick_init_req_sg'
memstick.c:265: warning: Function parameter or struct member 'tpc' not described in 'memstick_init_req_sg'
memstick.c:265: warning: Function parameter or struct member 'sg' not described in 'memstick_init_req_sg'
memstick.c:295: warning: Function parameter or struct member 'mrq' not described in 'memstick_init_req'
memstick.c:295: warning: Function parameter or struct member 'tpc' not described in 'memstick_init_req'
memstick.c:295: warning: Function parameter or struct member 'buf' not described in 'memstick_init_req'
memstick.c:295: warning: Function parameter or struct member 'length' not described in 'memstick_init_req'
memstick.c:366: warning: Function parameter or struct member 'card' not described in 'memstick_set_rw_addr'
memstick.c:513: warning: Function parameter or struct member 'host' not described in 'memstick_add_host'
memstick.c:549: warning: Function parameter or struct member 'host' not described in 'memstick_remove_host'
memstick.c:571: warning: Function parameter or struct member 'host' not described in 'memstick_free_host'
memstick.c:582: warning: Function parameter or struct member 'host' not described in 'memstick_suspend_host'
memstick.c:594: warning: Function parameter or struct member 'host' not described in 'memstick_resume_host'

Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
Cc: Maxim Levitsky <maximlevitsky@...il.com>
Cc: Alex Dubov <oakad@...oo.com>
Cc: Ulf Hansson <ulf.hansson@...aro.org>
Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc: linux-mmc@...r.kernel.org
---
 drivers/memstick/core/memstick.c |   46 +++++++++++++++++------------
 1 file changed, 27 insertions(+), 19 deletions(-)

--- linux-next-20250108.orig/drivers/memstick/core/memstick.c
+++ linux-next-20250108/drivers/memstick/core/memstick.c
@@ -200,7 +200,7 @@ static int memstick_dummy_check(struct m
 
 /**
  * memstick_detect_change - schedule media detection on memstick host
- * @host - host to use
+ * @host: host to use
  */
 void memstick_detect_change(struct memstick_host *host)
 {
@@ -210,13 +210,15 @@ EXPORT_SYMBOL(memstick_detect_change);
 
 /**
  * memstick_next_req - called by host driver to obtain next request to process
- * @host - host to use
- * @mrq - pointer to stick the request to
+ * @host: host to use
+ * @mrq: pointer to stick the request to
  *
  * Host calls this function from idle state (*mrq == NULL) or after finishing
  * previous request (*mrq should point to it). If previous request was
- * unsuccessful, it is retried for predetermined number of times. Return value
- * of 0 means that new request was assigned to the host.
+ * unsuccessful, it is retried for predetermined number of times.
+ *
+ * Returns: value of 0 means that new request was assigned to the host.
+ * Otherwise a negative error code is returned.
  */
 int memstick_next_req(struct memstick_host *host, struct memstick_request **mrq)
 {
@@ -242,7 +244,7 @@ EXPORT_SYMBOL(memstick_next_req);
 
 /**
  * memstick_new_req - notify the host that some requests are pending
- * @host - host to use
+ * @host: host to use
  */
 void memstick_new_req(struct memstick_host *host)
 {
@@ -256,9 +258,9 @@ EXPORT_SYMBOL(memstick_new_req);
 
 /**
  * memstick_init_req_sg - set request fields needed for bulk data transfer
- * @mrq - request to use
- * @tpc - memstick Transport Protocol Command
- * @sg - TPC argument
+ * @mrq: request to use
+ * @tpc: memstick Transport Protocol Command
+ * @sg: TPC argument
  */
 void memstick_init_req_sg(struct memstick_request *mrq, unsigned char tpc,
 			  const struct scatterlist *sg)
@@ -281,10 +283,10 @@ EXPORT_SYMBOL(memstick_init_req_sg);
 
 /**
  * memstick_init_req - set request fields needed for short data transfer
- * @mrq - request to use
- * @tpc - memstick Transport Protocol Command
- * @buf - TPC argument buffer
- * @length - TPC argument size
+ * @mrq: request to use
+ * @tpc: memstick Transport Protocol Command
+ * @buf: TPC argument buffer
+ * @length: TPC argument size
  *
  * The intended use of this function (transfer of data items several bytes
  * in size) allows us to just copy the value between request structure and
@@ -360,7 +362,9 @@ static int h_memstick_set_rw_addr(struct
 /**
  * memstick_set_rw_addr - issue SET_RW_REG_ADDR request and wait for it to
  *                        complete
- * @card - media device to use
+ * @card: media device to use
+ *
+ * Returns: error setting for the current request
  */
 int memstick_set_rw_addr(struct memstick_dev *card)
 {
@@ -487,6 +491,8 @@ out_power_off:
  * memstick_alloc_host - allocate a memstick_host structure
  * @extra: size of the user private data to allocate
  * @dev: parent device of the host
+ *
+ * Returns: %NULL on failure or the allocated &memstick_host pointer on success
  */
 struct memstick_host *memstick_alloc_host(unsigned int extra,
 					  struct device *dev)
@@ -507,7 +513,9 @@ EXPORT_SYMBOL(memstick_alloc_host);
 
 /**
  * memstick_add_host - start request processing on memstick host
- * @host - host to use
+ * @host: host to use
+ *
+ * Returns: %0 on success or a negative error code on failure
  */
 int memstick_add_host(struct memstick_host *host)
 {
@@ -543,7 +551,7 @@ EXPORT_SYMBOL(memstick_add_host);
 
 /**
  * memstick_remove_host - stop request processing on memstick host
- * @host - host to use
+ * @host: host to use
  */
 void memstick_remove_host(struct memstick_host *host)
 {
@@ -565,7 +573,7 @@ EXPORT_SYMBOL(memstick_remove_host);
 
 /**
  * memstick_free_host - free memstick host
- * @host - host to use
+ * @host: host to use
  */
 void memstick_free_host(struct memstick_host *host)
 {
@@ -576,7 +584,7 @@ EXPORT_SYMBOL(memstick_free_host);
 
 /**
  * memstick_suspend_host - notify bus driver of host suspension
- * @host - host to use
+ * @host: host to use
  */
 void memstick_suspend_host(struct memstick_host *host)
 {
@@ -588,7 +596,7 @@ EXPORT_SYMBOL(memstick_suspend_host);
 
 /**
  * memstick_resume_host - notify bus driver of host resumption
- * @host - host to use
+ * @host: host to use
  */
 void memstick_resume_host(struct memstick_host *host)
 {

Powered by blists - more mailing lists