scsi_transport_srp.c kernel-doc warnings

The following command has been used to verify that the kernel-doc tool no longer complains about undocumented fields:

scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
include/scsi/scsi_transport_srp.h >srp-transport-doc.html

Signed-off-by Bart Van Assche <[email protected]>

Cc David Dillow <[email protected]>

Cc Vu Pham <[email protected]>

Cc Sebastian Riemer <[email protected]>

Cc James Bottomley <[email protected]>

Cc Randy Dunlap <[email protected]>

---
 drivers/scsi/scsi_transport_srp.c | 12 ++++++++++++
 include/scsi/scsi_transport_srp.h | 32 ++++++++++++++++++++++++++++----
 2 files changed, 40 insertions(+), 4 deletions(-)

drivers/scsi/scsi_transport_srp.c +3 -0

index 2700a5a..96ffc46 100644
@@ -64,6 +64,9 @@ static inline struct Scsi_Host *rport_to_shost(struct
 srp_rport *r)
 
 /**
  * srp_tmo_valid() - check timeout combination validity
+ * @reconnect_delay: Reconnect delay in seconds.
+ * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
+ * @dev_loss_tmo: Device loss timeout in seconds.
  *
  * The combination of the timeout parameters must be such that SCSI

commands

* are finished in a reasonable time. Hence do not allow the fast I/O fail

drivers/scsi/scsi_transport_srp.c +2 -0

@@ -368,6 +371,7 @@ invalid:
 
 /**
  * srp_reconnect_work() - reconnect and schedule a new attempt if necessary
+ * @work: Work structure used for scheduling this operation.
  */
 static void srp_reconnect_work(struct work_struct *work)
 {

@@ -408,6 +412,7 @@ static void __rport_fail_io_fast(struct srp_rport
 *rport)
 
 /**
  * rport_fast_io_fail_timedout() - fast I/O failure timeout handler
+ * @work: Work structure used for scheduling this operation.
  */
 static void rport_fast_io_fail_timedout(struct work_struct *work)

{

drivers/scsi/scsi_transport_srp.c +1 -0

@@ -426,6 +431,7 @@ static void rport_fast_io_fail_timedout(struct
 work_struct *work)
 
 /**
  * rport_dev_loss_timedout() - device loss timeout handler
+ * @work: Work structure used for scheduling this operation.
  */
 static void rport_dev_loss_timedout(struct work_struct *work)

{

drivers/scsi/scsi_transport_srp.c +1 -0

@@ -488,6 +494,7 @@ static void __srp_start_tl_fail_timers(struct
 srp_rport *rport)
 
 /**
  * srp_start_tl_fail_timers() - start the transport layer failure timers
+ * @rport: SRP target port.
  *
  * Start the transport layer fast I/O failure and device loss timers.

Do not
* modify a timer that was already started.

drivers/scsi/scsi_transport_srp.c +1 -0

@@ -502,6 +509,7 @@ EXPORT_SYMBOL(srp_start_tl_fail_timers);
 
 /**
  * scsi_request_fn_active() - number of kernel threads inside
 scsi_request_fn()
+ * @shost: SCSI host for which to count the number of scsi_request_fn()

callers.
*/
static int scsi_request_fn_active(struct Scsi_Host *shost) {

drivers/scsi/scsi_transport_srp.c +1 -0

@@ -522,6 +530,7 @@ static int scsi_request_fn_active(struct Scsi_Host
 *shost)
 
 /**
  * srp_reconnect_rport() - reconnect to an SRP target port
+ * @rport: SRP target port.
  *
  * Blocks SCSI command queueing before invoking reconnect() such that

* queuecommand() won't be invoked concurrently with reconnect() from
outside

drivers/scsi/scsi_transport_srp.c +2 -0

@@ -599,6 +608,7 @@ EXPORT_SYMBOL(srp_reconnect_rport);
 
 /**
  * srp_timed_out() - SRP transport intercept of the SCSI timeout EH
+ * @scmd: SCSI command.
  *
  * If a timeout occurs while an rport is in the blocked state, ask the SCSI
  * EH to continue waiting (BLK_EH_RESET_TIMER). Otherwise let the SCSI core

@@ -674,6 +684,7 @@ static int srp_host_match(struct attribute_container
 *cont, struct device *dev)
 
 /**
  * srp_rport_get() - increment rport reference count
+ * @rport: SRP target port.
  */
 void srp_rport_get(struct srp_rport *rport)

{

drivers/scsi/scsi_transport_srp.c +1 -0

@@ -683,6 +694,7 @@ EXPORT_SYMBOL(srp_rport_get);
 
 /**
  * srp_rport_put() - decrement rport reference count
+ * @rport: SRP target port.
  */
 void srp_rport_put(struct srp_rport *rport)
 {

include/scsi/scsi_transport_srp.h +13 -4

index 4ebf691..69eb021 100644
@@ -29,10 +29,26 @@ enum srp_rport_state {
 };
 
 /**
- * struct srp_rport
- * @lld_data: LLD private data.
- * @mutex:    Protects against concurrent rport reconnect / fast_io_fail /
- *   dev_loss_tmo activity.
+ * struct srp_rport - SRP initiator or target port
+ *
+ * Fields that are relevant for SRP initiator and SRP target drivers:
+ * @dev:               Device associated with this rport.
+ * @port_id:           16-byte port identifier.
+ * @roles:             Role of this port - initiator or target.
+ *
+ * Fields that are only relevant for SRP initiator drivers:
+ * @lld_data:          LLD private data.
+ * @mutex:             Protects against concurrent rport reconnect /
+ *                     fast_io_fail / dev_loss_tmo activity.
+ * @state:             rport state.
+ * @deleted:           Whether or not srp_rport_del() has already been

invoked.
+ * @reconnect_delay: Reconnect delay in seconds.
+ * @failed_reconnects: Number of failed reconnect attempts.
+ * @reconnect_work: Work structure used for scheduling reconnect
attempts.
+ * @fast_io_fail_tmo: Fast I/O fail timeout in seconds.
+ * @dev_loss_tmo: Device loss timeout in seconds.
+ * @fast_io_fail_work: Work structure used for scheduling fast I/O fail work.
+ * @dev_loss_work: Work structure used for scheduling device loss work.
*/

 struct srp_rport {
     /* for initiator and target drivers */

include/scsi/scsi_transport_srp.h +2 -0

@@ -60,6 +76,8 @@ struct srp_rport {
 
 /**
  * struct srp_function_template
+ *
+ * Fields that are only relevant for SRP initiator drivers:
  * @has_rport_state: Whether or not to create the state,

fast_io_fail_tmo and
* dev_loss_tmo sysfs attribute for an rport.
* @reset_timer_if_blocked: Whether or srp_timed_out() should reset the
command

include/scsi/scsi_transport_srp.h +0 -0

@@ -71,6 +89,11 @@ struct srp_rport {
  *     srp_reconnect_rport().
  * @terminate_rport_io: Callback function for terminating all

outstanding I/O
* requests for an rport.
+ * @rport_delete: Callback function that deletes an rport.
+ *
+ * Fields that are only relevant for SRP target drivers:
+ * @tsk_mgmt_response: Callback function for sending a task management response.
+ * @it_nexus_response: Callback function for processing an IT nexus response.
*/

 struct srp_function_template {
     /* for initiator drivers */

include/scsi/scsi_transport_srp.h +1 -0

@@ -104,6 +127,7 @@ extern void srp_remove_host(struct Scsi_Host *);
 
 /**
  * srp_chkready() - evaluate the transport layer state before I/O
+ * @rport: SRP target port pointer.
  *
  * Returns a SCSI result code that can be returned by the LLD
 queuecommand()

* implementation. The role of this function is similar to that of

Quoted 5 lines · Bart Van Assche

The following command has been used to verify that the kernel-doc tool no longer complains about undocumented fields:

scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
include/scsi/scsi_transport_srp.h >srp-transport-doc.html

Thanks for the patch.
I guess that your tree is different from mine. Using 3.13-rc7, I still get 3 warnings:

Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for parameter 'scmd' Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for parameter 'rport' Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for parameter 'rport'

I also had some trouble with the patch itself -- looks like some of its longer lines were broken (split) by your mail app (I'm guessing).
The first split line is marked below.

From 6dc06b90bf848ec9bb498495b21c66b168726ef4 Mon Sep 17 00:00:00 2001

Quoted 15 lines · Randy Dunlap

Quoted 5 lines · Bart Van Assche

The following command has been used to verify that the kernel-doc tool no longer complains about undocumented fields:

scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
include/scsi/scsi_transport_srp.h >srp-transport-doc.html

Thanks for the patch.
I guess that your tree is different from mine. Using 3.13-rc7, I still get 3 warnings:

Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for parameter 'scmd' Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for parameter 'rport' Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for parameter 'rport'

Quoted 3 lines

I also had some trouble with the patch itself -- looks like some of its longer lines were broken (split) by your mail app (I'm guessing).
The first split line is marked below.

Sorry but it seems like my e-mail client line-wrapped the patch. Does the attached patch work better ? The attached patch should be identical to what I posted except for the line wrapping. I do not see the warnings mentioned above - maybe these were introduced by the line wrapping ?

Quoted 15 lines · Randy Dunlap

Quoted 5 lines · Bart Van Assche

The following command has been used to verify that the kernel-doc tool no longer complains about undocumented fields:

scripts/kernel-doc -html drivers/scsi/scsi_transport_srp.c \
include/scsi/scsi_transport_srp.h >srp-transport-doc.html

Thanks for the patch.
I guess that your tree is different from mine. Using 3.13-rc7, I still get 3 warnings:

Warning(drivers/scsi/scsi_transport_srp.c:620): No description found for parameter 'scmd' Warning(drivers/scsi/scsi_transport_srp.c:688): No description found for parameter 'rport' Warning(drivers/scsi/scsi_transport_srp.c:697): No description found for parameter 'rport'

Quoted 3 lines

I also had some trouble with the patch itself -- looks like some of its longer lines were broken (split) by your mail app (I'm guessing).
The first split line is marked below.

Sorry but it seems like my e-mail client line-wrapped the patch. Does the attached patch work better ? The attached patch should be identical to what I posted except for the line wrapping. I do not see the warnings mentioned above - maybe these were introduced by the line wrapping ?