History

scsi: libfc: Add some kernel-doc comments

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'

Randy Dunlap committed 2 years ago

Commit 9cef74a1 parent 2a7177a1 file · +15 −3Browse files

Unified · Split

include/scsi/libfc.h+15−3
@@ -44,11 +44,16 @@ · 43 unmodified lines
44 * @LPORT_ST_DISABLED: Disabled44 * @LPORT_ST_DISABLED: Disabled
45 * @LPORT_ST_FLOGI: Fabric login (FLOGI) sent45 * @LPORT_ST_FLOGI: Fabric login (FLOGI) sent
46 * @LPORT_ST_DNS: Waiting for name server remote port to become ready46 * @LPORT_ST_DNS: Waiting for name server remote port to become ready
47 * @LPORT_ST_RPN_ID: Register port name by ID (RPN_ID) sent47 * @LPORT_ST_RNN_ID: Register port name by ID (RNN_ID) sent
48 * @LPORT_ST_RSNN_NN: Waiting for host symbolic node name
49 * @LPORT_ST_RSPN_ID: Waiting for host symbolic port name
48 * @LPORT_ST_RFT_ID: Register Fibre Channel types by ID (RFT_ID) sent50 * @LPORT_ST_RFT_ID: Register Fibre Channel types by ID (RFT_ID) sent
49 * @LPORT_ST_RFF_ID: Register FC-4 Features by ID (RFF_ID) sent51 * @LPORT_ST_RFF_ID: Register FC-4 Features by ID (RFF_ID) sent
50 * @LPORT_ST_FDMI: Waiting for mgmt server rport to become ready52 * @LPORT_ST_FDMI: Waiting for mgmt server rport to become ready
51 * @LPORT_ST_RHBA:53 * @LPORT_ST_RHBA: Register HBA
54 * @LPORT_ST_RPA: Register Port Attributes
55 * @LPORT_ST_DHBA: Deregister HBA
56 * @LPORT_ST_DPRT: Deregister Port
52 * @LPORT_ST_SCR: State Change Register (SCR) sent57 * @LPORT_ST_SCR: State Change Register (SCR) sent
53 * @LPORT_ST_READY: Ready for use58 * @LPORT_ST_READY: Ready for use
54 * @LPORT_ST_LOGO: Local port logout (LOGO) sent59 * @LPORT_ST_LOGO: Local port logout (LOGO) sent
@@ -183,7 +188,7 @@ struct fc_rport_libfc_priv { · 128 unmodified lines
183 * @r_a_tov: Resource allocation timeout value (in msec)188 * @r_a_tov: Resource allocation timeout value (in msec)
184 * @rp_mutex: The mutex that protects the remote port189 * @rp_mutex: The mutex that protects the remote port
185 * @retry_work: Handle for retries190 * @retry_work: Handle for retries
186 * @event_callback: Callback when READY, FAILED or LOGO states complete191 * @lld_event_callback: Callback when READY, FAILED or LOGO states complete
187 * @prli_count: Count of open PRLI sessions in providers192 * @prli_count: Count of open PRLI sessions in providers
188 * @rcu: Structure used for freeing in an RCU-safe manner193 * @rcu: Structure used for freeing in an RCU-safe manner
189 */194 */
@@ -289,6 +294,7 @@ struct fc_seq_els_data { · 99 unmodified lines
289 * @timer: The command timer294 * @timer: The command timer
290 * @tm_done: Completion indicator295 * @tm_done: Completion indicator
291 * @wait_for_comp: Indicator to wait for completion of the I/O (in jiffies)296 * @wait_for_comp: Indicator to wait for completion of the I/O (in jiffies)
297 * @timer_delay: FCP packet timer delay in jiffies
292 * @data_len: The length of the data298 * @data_len: The length of the data
293 * @cdb_cmd: The CDB command299 * @cdb_cmd: The CDB command
294 * @xfer_len: The transfer length300 * @xfer_len: The transfer length
@@ -788,6 +794,8 @@ void fc_fc4_deregister_provider(enum fc_fh_type type, struct fc4_prov *); · 493 unmodified lines
788/**794/**
789 * fc_lport_test_ready() - Determine if a local port is in the READY state795 * fc_lport_test_ready() - Determine if a local port is in the READY state
790 * @lport: The local port to test796 * @lport: The local port to test
797 *
798 * Returns: %true if local port is in the READY state, %false otherwise
791 */799 */
792static inline int fc_lport_test_ready(struct fc_lport *lport)800static inline int fc_lport_test_ready(struct fc_lport *lport)
793{801{
@@ -830,6 +838,8 @@ static inline void fc_lport_state_enter(struct fc_lport *lport, · 36 unmodified lines
830/**838/**
831 * fc_lport_init_stats() - Allocate per-CPU statistics for a local port839 * fc_lport_init_stats() - Allocate per-CPU statistics for a local port
832 * @lport: The local port whose statistics are to be initialized840 * @lport: The local port whose statistics are to be initialized
841 *
842 * Returns: %0 on success, %-ENOMEM on failure
833 */843 */
834static inline int fc_lport_init_stats(struct fc_lport *lport)844static inline int fc_lport_init_stats(struct fc_lport *lport)
835{845{
@@ -851,6 +861,8 @@ static inline void fc_lport_free_stats(struct fc_lport *lport) · 15 unmodified lines
851/**861/**
852 * lport_priv() - Return the private data from a local port862 * lport_priv() - Return the private data from a local port
853 * @lport: The local port whose private data is to be retrieved863 * @lport: The local port whose private data is to be retrieved
864 *
865 * Returns: the local port's private data pointer
854 */866 */
855static inline void *lport_priv(const struct fc_lport *lport)867static inline void *lport_priv(const struct fc_lport *lport)
856{868{