[PATCH] scsi: libfc.h: add some kernel-doc comments

* [PATCH] scsi: libfc.h: add some kernel-doc comments
@ 2024-04-24  5:00 Randy Dunlap
  2024-04-25  1:29 ` Martin K. Petersen
  2024-05-07  1:59 ` Martin K. Petersen
  0 siblings, 2 replies; 3+ messages in thread
From: Randy Dunlap @ 2024-04-24  5:00 UTC (permalink / raw)
  To: linux-scsi
  Cc: Randy Dunlap, Hannes Reinecke, James E.J. Bottomley, Martin K. Petersen

Complete the kernel-doc notation for enum fc_lport_state. This fixes
7 kernel-doc warnings.
In struct fc_rport_priv, change 'event_callback' to 'lld_event_callback'
to match the struct member name.
In struct fc_fcp_pkt, add a description for 'timer_delay' to eliminate
one kernel-doc warning.
Add return value notation for 3 functions. This fixes 3 kernel-doc
warnings.

There are still 12 warnings for struct members not described in struct
fc_rport_priv and struct fc_lport, e.g:

libfc.h:218: warning: Function parameter or struct member 'event' not described in 'fc_rport_priv'
libfc.h:760: warning: Function parameter or struct member 'vlan' not described in 'fc_lport'

Warnings that are fixed in this patch:

libfc.h:75: warning: Enum value 'LPORT_ST_RNN_ID' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RSNN_NN' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RSPN_ID' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_RPA' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_DHBA' not described in enum 'fc_lport_state'
libfc.h:75: warning: Enum value 'LPORT_ST_DPRT' not described in enum 'fc_lport_state'
libfc.h:75: warning: Excess enum value 'LPORT_ST_RPN_ID' description in 'fc_lport_state'

libfc.h:218: warning: Excess struct member 'event_callback' description in 'fc_rport_priv'

libfc.h:793: warning: No description found for return value of 'fc_lport_test_ready'
libfc.h:835: warning: No description found for return value of 'fc_lport_init_stats'
libfc.h:856: warning: No description found for return value of 'lport_priv'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Hannes Reinecke <hare@suse.de>
Cc: "James E.J. Bottomley" <James.Bottomley@HansenPartnership.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
---
 include/scsi/libfc.h |   18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff -- a/include/scsi/libfc.h b/include/scsi/libfc.h

--- a/include/scsi/libfc.h
+++ b/include/scsi/libfc.h
@@ -44,11 +44,16 @@
  * @LPORT_ST_DISABLED: Disabled
  * @LPORT_ST_FLOGI:    Fabric login (FLOGI) sent
  * @LPORT_ST_DNS:      Waiting for name server remote port to become ready
- * @LPORT_ST_RPN_ID:   Register port name by ID (RPN_ID) sent
+ * @LPORT_ST_RNN_ID:   Register port name by ID (RNN_ID) sent
+ * @LPORT_ST_RSNN_NN:  Waiting for host symbolic node name
+ * @LPORT_ST_RSPN_ID:  Waiting for host symbolic port name
  * @LPORT_ST_RFT_ID:   Register Fibre Channel types by ID (RFT_ID) sent
  * @LPORT_ST_RFF_ID:   Register FC-4 Features by ID (RFF_ID) sent
  * @LPORT_ST_FDMI:     Waiting for mgmt server rport to become ready
- * @LPORT_ST_RHBA:
+ * @LPORT_ST_RHBA:     Register HBA
+ * @LPORT_ST_RPA:      Register Port Attributes
+ * @LPORT_ST_DHBA:     Deregister HBA
+ * @LPORT_ST_DPRT:     Deregister Port
  * @LPORT_ST_SCR:      State Change Register (SCR) sent
  * @LPORT_ST_READY:    Ready for use
  * @LPORT_ST_LOGO:     Local port logout (LOGO) sent
@@ -183,7 +188,7 @@ struct fc_rport_libfc_priv {
  * @r_a_tov:        Resource allocation timeout value (in msec)
  * @rp_mutex:       The mutex that protects the remote port
  * @retry_work:     Handle for retries
- * @event_callback: Callback when READY, FAILED or LOGO states complete
+ * @lld_event_callback: Callback when READY, FAILED or LOGO states complete
  * @prli_count:     Count of open PRLI sessions in providers
  * @rcu:	    Structure used for freeing in an RCU-safe manner
  */
@@ -289,6 +294,7 @@ struct fc_seq_els_data {
  * @timer:           The command timer
  * @tm_done:         Completion indicator
  * @wait_for_comp:   Indicator to wait for completion of the I/O (in jiffies)
+ * @timer_delay:     FCP packet timer delay in jiffies
  * @data_len:        The length of the data
  * @cdb_cmd:         The CDB command
  * @xfer_len:        The transfer length
@@ -788,6 +794,8 @@ void fc_fc4_deregister_provider(enum fc_
 /**
  * fc_lport_test_ready() - Determine if a local port is in the READY state
  * @lport: The local port to test
+ *
+ * Returns: %true if local port is in the READY state, %false otherwise
  */
 static inline int fc_lport_test_ready(struct fc_lport *lport)
 {
@@ -830,6 +838,8 @@ static inline void fc_lport_state_enter(
 /**
  * fc_lport_init_stats() - Allocate per-CPU statistics for a local port
  * @lport: The local port whose statistics are to be initialized
+ *
+ * Returns: %0 on success, %-ENOMEM on failure
  */
 static inline int fc_lport_init_stats(struct fc_lport *lport)
 {
@@ -851,6 +861,8 @@ static inline void fc_lport_free_stats(s
 /**
  * lport_priv() - Return the private data from a local port
  * @lport: The local port whose private data is to be retrieved
+ *
+ * Returns: the local port's private data pointer
  */
 static inline void *lport_priv(const struct fc_lport *lport)
 {

^ permalink raw reply	[flat|nested] 3+ messages in thread