[PATCH 5/8] scsi: libfcoe: fix a slew of kernel-doc warnings

[Randy Dunlap <rdunlap@infradead.org>]

Fix all kernel-doc warnings in <scsi/libfcoe.h>:

libfcoe.h:163: warning: Function parameter or struct member 'ctlr' not described in 'fcoe_ctlr_priv'
libfcoe.h:163: warning: Excess function parameter 'cltr' description in 'fcoe_ctlr_priv'
libfcoe.h:163: warning: No description found for return value of 'fcoe_ctlr_priv'
libfcoe.h:218: warning: Function parameter or struct member 'fd_flags' not described in 'fcoe_fcf'
libfcoe.h:218: warning: Excess struct member 'event' description in 'fcoe_fcf'
libfcoe.h:240: warning: Function parameter or struct member 'rdata' not described in 'fcoe_rport'
libfcoe.h:273: warning: No description found for return value of 'is_fip_mode'
libfcoe.h:332: warning: Function parameter or struct member 'crc_eof_page' not described in 'fcoe_percpu_s'
libfcoe.h:332: warning: Function parameter or struct member 'lock' not described in 'fcoe_percpu_s'
libfcoe.h:332: warning: Excess struct member 'page' description in 'fcoe_percpu_s'
libfcoe.h:362: warning: Function parameter or struct member 'data_src_addr' not described in 'fcoe_port'
libfcoe.h:362: warning: Function parameter or struct member 'get_netdev' not described in 'fcoe_port'
libfcoe.h:362: warning: Excess struct member 'data_srt_addr' description in 'fcoe_port'
libfcoe.h:369: warning: No description found for return value of 'fcoe_get_netdev'
libfcoe.h:386: warning: missing initial short description on line:
 * struct netdev_list
libfcoe.h:393: warning: expecting prototype for struct netdev_list. Prototype was for struct fcoe_netdev_mapping instead

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Hannes Reinecke <hare@suse.de>

 include/scsi/libfcoe.h |   25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff -- a/include/scsi/libfcoe.h b/include/scsi/libfcoe.h
--- a/include/scsi/libfcoe.h
+++ b/include/scsi/libfcoe.h
@@ -157,7 +157,9 @@ struct fcoe_ctlr {
 
 /**
  * fcoe_ctlr_priv() - Return the private data from a fcoe_ctlr
- * @cltr: The fcoe_ctlr whose private data will be returned
+ * @ctlr: The fcoe_ctlr whose private data will be returned
+ *
+ * Returns: pointer to the private data
  */
 static inline void *fcoe_ctlr_priv(const struct fcoe_ctlr *ctlr)
 {
@@ -174,7 +176,6 @@ static inline void *fcoe_ctlr_priv(const
  * struct fcoe_fcf - Fibre-Channel Forwarder
  * @list:	 list linkage
  * @event_work:  Work for FC Transport actions queue
- * @event:       The event to be processed
  * @fip:         The controller that the FCF was discovered on
  * @fcf_dev:     The associated fcoe_fcf_device instance
  * @time:	 system time (jiffies) when an advertisement was last received
@@ -188,6 +189,7 @@ static inline void *fcoe_ctlr_priv(const
  * @flogi_sent:	 current FLOGI sent to this FCF
  * @flags:	 flags received from advertisement
  * @fka_period:	 keep-alive period, in jiffies
+ * @fd_flags:	 no need for FKA from ENode
  *
  * A Fibre-Channel Forwarder (FCF) is the entity on the Ethernet that
  * passes FCoE frames on to an FC fabric.  This structure represents
@@ -222,6 +224,7 @@ struct fcoe_fcf {
 
 /**
  * struct fcoe_rport - VN2VN remote port
+ * @rdata:	libfc remote port private data
  * @time:	time of create or last beacon packet received from node
  * @fcoe_len:	max FCoE frame size, not including VLAN or Ethernet headers
  * @flags:	flags from probe or claim
@@ -266,8 +269,10 @@ void fcoe_get_lesb(struct fc_lport *, st
 void fcoe_ctlr_get_lesb(struct fcoe_ctlr_device *ctlr_dev);
 
 /**
- * is_fip_mode() - returns true if FIP mode selected.
+ * is_fip_mode() - test if FIP mode selected.
  * @fip:	FCoE controller.
+ *
+ * Returns: %true if FIP mode is selected
  */
 static inline bool is_fip_mode(struct fcoe_ctlr *fip)
 {
@@ -318,9 +323,10 @@ struct fcoe_transport {
  * @kthread:	    The thread context (used by bnx2fc)
  * @work:	    The work item (used by fcoe)
  * @fcoe_rx_list:   The queue of pending packets to process
- * @page:	    The memory page for calculating frame trailer CRCs
+ * @crc_eof_page:   The memory page for calculating frame trailer CRCs
  * @crc_eof_offset: The offset into the CRC page pointing to available
  *		    memory for a new trailer
+ * @lock:	    local lock for members of this struct
  */
 struct fcoe_percpu_s {
 	struct task_struct *kthread;
@@ -343,7 +349,8 @@ struct fcoe_percpu_s {
  * @timer:		       The queue timer
  * @destroy_work:	       Handle for work context
  *			       (to prevent RTNL deadlocks)
- * @data_srt_addr:	       Source address for data
+ * @data_src_addr:	       Source address for data
+ * @get_netdev:                function that returns a &net_device from @lport
  *
  * An instance of this structure is to be allocated along with the
  * Scsi_Host and libfc fc_lport structures.
@@ -364,6 +371,8 @@ struct fcoe_port {
 /**
  * fcoe_get_netdev() - Return the net device associated with a local port
  * @lport: The local port to get the net device from
+ *
+ * Returns: the &net_device associated with this @lport
  */
 static inline struct net_device *fcoe_get_netdev(const struct fc_lport *lport)
 {
@@ -383,8 +392,10 @@ void fcoe_fcf_get_selected(struct fcoe_f
 void fcoe_ctlr_set_fip_mode(struct fcoe_ctlr_device *);
 
 /**
- * struct netdev_list
- * A mapping from netdevice to fcoe_transport
+ * struct fcoe_netdev_mapping - A mapping from &net_device to &fcoe_transport
+ * @list: list linkage of the mappings
+ * @netdev: the &net_device
+ * @ft: the fcoe_transport associated with @netdev
  */
 struct fcoe_netdev_mapping {
 	struct list_head list;