diff mbox series

[5/8] net: ethernet: ibm: ibmvnic: Fix some kernel-doc misdemeanours

Message ID 20201126133853.3213268-6-lee.jones@linaro.org
State New
Headers show
Series Rid W=1 warnings in Net | expand

Commit Message

Lee Jones Nov. 26, 2020, 1:38 p.m. UTC
Fixes the following W=1 kernel build warning(s):

 from drivers/net/ethernet/ibm/ibmvnic.c:35:
 inlined from ‘handle_vpd_rsp’ at drivers/net/ethernet/ibm/ibmvnic.c:4124:3:
 drivers/net/ethernet/ibm/ibmvnic.c:1362: warning: Function parameter or member 'hdr_field' not described in 'build_hdr_data'
 drivers/net/ethernet/ibm/ibmvnic.c:1362: warning: Function parameter or member 'skb' not described in 'build_hdr_data'
 drivers/net/ethernet/ibm/ibmvnic.c:1362: warning: Function parameter or member 'hdr_len' not described in 'build_hdr_data'
 drivers/net/ethernet/ibm/ibmvnic.c:1362: warning: Function parameter or member 'hdr_data' not described in 'build_hdr_data'
 drivers/net/ethernet/ibm/ibmvnic.c:1423: warning: Function parameter or member 'hdr_field' not described in 'create_hdr_descs'
 drivers/net/ethernet/ibm/ibmvnic.c:1423: warning: Function parameter or member 'hdr_data' not described in 'create_hdr_descs'
 drivers/net/ethernet/ibm/ibmvnic.c:1423: warning: Function parameter or member 'len' not described in 'create_hdr_descs'
 drivers/net/ethernet/ibm/ibmvnic.c:1423: warning: Function parameter or member 'hdr_len' not described in 'create_hdr_descs'
 drivers/net/ethernet/ibm/ibmvnic.c:1423: warning: Function parameter or member 'scrq_arr' not described in 'create_hdr_descs'
 drivers/net/ethernet/ibm/ibmvnic.c:1474: warning: Function parameter or member 'txbuff' not described in 'build_hdr_descs_arr'
 drivers/net/ethernet/ibm/ibmvnic.c:1474: warning: Function parameter or member 'num_entries' not described in 'build_hdr_descs_arr'
 drivers/net/ethernet/ibm/ibmvnic.c:1474: warning: Function parameter or member 'hdr_field' not described in 'build_hdr_descs_arr'
 drivers/net/ethernet/ibm/ibmvnic.c:1832: warning: Function parameter or member 'adapter' not described in 'do_change_param_reset'
 drivers/net/ethernet/ibm/ibmvnic.c:1832: warning: Function parameter or member 'rwi' not described in 'do_change_param_reset'
 drivers/net/ethernet/ibm/ibmvnic.c:1832: warning: Function parameter or member 'reset_state' not described in 'do_change_param_reset'
 drivers/net/ethernet/ibm/ibmvnic.c:1911: warning: Function parameter or member 'adapter' not described in 'do_reset'
 drivers/net/ethernet/ibm/ibmvnic.c:1911: warning: Function parameter or member 'rwi' not described in 'do_reset'
 drivers/net/ethernet/ibm/ibmvnic.c:1911: warning: Function parameter or member 'reset_state' not described in 'do_reset'

Cc: Dany Madden <drt@linux.ibm.com>
Cc: Lijun Pan <ljp@linux.ibm.com>
Cc: Sukadev Bhattiprolu <sukadev@linux.ibm.com>
Cc: Michael Ellerman <mpe@ellerman.id.au>
Cc: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Cc: Paul Mackerras <paulus@samba.org>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Santiago Leon <santi_leon@yahoo.com>
Cc: Thomas Falcon <tlfalcon@linux.vnet.ibm.com>
Cc: John Allen <jallen@linux.vnet.ibm.com>
Cc: netdev@vger.kernel.org
Cc: linuxppc-dev@lists.ozlabs.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>

---
 drivers/net/ethernet/ibm/ibmvnic.c | 28 ++++++++++++++--------------
 drivers/net/xen-netfront.c         |  6 +++---
 2 files changed, 17 insertions(+), 17 deletions(-)

-- 
2.25.1

Comments

Andrew Lunn Nov. 29, 2020, 6:43 p.m. UTC | #1
Hi Lee

>  /**

>   * build_hdr_data - creates L2/L3/L4 header data buffer

> - * @hdr_field - bitfield determining needed headers

> - * @skb - socket buffer

> - * @hdr_len - array of header lengths

> - * @tot_len - total length of data

> + * @hdr_field: bitfield determining needed headers

> + * @skb: socket buffer

> + * @hdr_len: array of header lengths

> + * @tot_len: total length of data

>   *

>   * Reads hdr_field to determine which headers are needed by firmware.

>   * Builds a buffer containing these headers.  Saves individual header


The code is:

static int build_hdr_data(u8 hdr_field, struct sk_buff *skb,
                          int *hdr_len, u8 *hdr_data)
{

What about hdr_data? 

>  /**

>   * create_hdr_descs - create header and header extension descriptors

> - * @hdr_field - bitfield determining needed headers

> - * @data - buffer containing header data

> - * @len - length of data buffer

> - * @hdr_len - array of individual header lengths

> - * @scrq_arr - descriptor array

> + * @hdr_field: bitfield determining needed headers

> + * @data: buffer containing header data

> + * @len: length of data buffer

> + * @hdr_len: array of individual header lengths

> + * @scrq_arr: descriptor array


static int create_hdr_descs(u8 hdr_field, u8 *hdr_data, int len, int *hdr_len,
                            union sub_crq *scrq_arr)

There is no data parameter.

It looks like you just changes - to :, but did not validate the
parameters are actually correct.

	   Andrew
Lee Jones Nov. 30, 2020, 9:04 a.m. UTC | #2
On Sun, 29 Nov 2020, Andrew Lunn wrote:

> Hi Lee

> 

> >  /**

> >   * build_hdr_data - creates L2/L3/L4 header data buffer

> > - * @hdr_field - bitfield determining needed headers

> > - * @skb - socket buffer

> > - * @hdr_len - array of header lengths

> > - * @tot_len - total length of data

> > + * @hdr_field: bitfield determining needed headers

> > + * @skb: socket buffer

> > + * @hdr_len: array of header lengths

> > + * @tot_len: total length of data

> >   *

> >   * Reads hdr_field to determine which headers are needed by firmware.

> >   * Builds a buffer containing these headers.  Saves individual header

> 

> The code is:

> 

> static int build_hdr_data(u8 hdr_field, struct sk_buff *skb,

>                           int *hdr_len, u8 *hdr_data)

> {

> 

> What about hdr_data? 

> 

> >  /**

> >   * create_hdr_descs - create header and header extension descriptors

> > - * @hdr_field - bitfield determining needed headers

> > - * @data - buffer containing header data

> > - * @len - length of data buffer

> > - * @hdr_len - array of individual header lengths

> > - * @scrq_arr - descriptor array

> > + * @hdr_field: bitfield determining needed headers

> > + * @data: buffer containing header data

> > + * @len: length of data buffer

> > + * @hdr_len: array of individual header lengths

> > + * @scrq_arr: descriptor array

> 

> static int create_hdr_descs(u8 hdr_field, u8 *hdr_data, int len, int *hdr_len,

>                             union sub_crq *scrq_arr)

> 

> There is no data parameter.

> 

> It looks like you just changes - to :, but did not validate the

> parameters are actually correct.


Right.  This is a 'quirk' of my current process.

I build once, then use a script to parse the output, fixing each
issue in the order the compiler presents them.  Then, either after
fixing a reasonable collection, or all issues, I re-run the compile
and fix the next batch (if any).

This patch is only fixing the formatting issue(s).  As you've seen,
there is a subsequent patch in the series which fixes the disparity.

I can squash them though.  No problem.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
diff mbox series

Patch

diff --git a/drivers/net/ethernet/ibm/ibmvnic.c b/drivers/net/ethernet/ibm/ibmvnic.c
index b0884eba568d7..36ea37721e3c8 100644
--- a/drivers/net/ethernet/ibm/ibmvnic.c
+++ b/drivers/net/ethernet/ibm/ibmvnic.c
@@ -1376,10 +1376,10 @@  static int ibmvnic_close(struct net_device *netdev)
 
 /**
  * build_hdr_data - creates L2/L3/L4 header data buffer
- * @hdr_field - bitfield determining needed headers
- * @skb - socket buffer
- * @hdr_len - array of header lengths
- * @tot_len - total length of data
+ * @hdr_field: bitfield determining needed headers
+ * @skb: socket buffer
+ * @hdr_len: array of header lengths
+ * @tot_len: total length of data
  *
  * Reads hdr_field to determine which headers are needed by firmware.
  * Builds a buffer containing these headers.  Saves individual header
@@ -1436,11 +1436,11 @@  static int build_hdr_data(u8 hdr_field, struct sk_buff *skb,
 
 /**
  * create_hdr_descs - create header and header extension descriptors
- * @hdr_field - bitfield determining needed headers
- * @data - buffer containing header data
- * @len - length of data buffer
- * @hdr_len - array of individual header lengths
- * @scrq_arr - descriptor array
+ * @hdr_field: bitfield determining needed headers
+ * @data: buffer containing header data
+ * @len: length of data buffer
+ * @hdr_len: array of individual header lengths
+ * @scrq_arr: descriptor array
  *
  * Creates header and, if needed, header extension descriptors and
  * places them in a descriptor array, scrq_arr
@@ -1488,10 +1488,10 @@  static int create_hdr_descs(u8 hdr_field, u8 *hdr_data, int len, int *hdr_len,
 
 /**
  * build_hdr_descs_arr - build a header descriptor array
- * @skb - socket buffer
- * @num_entries - number of descriptors to be sent
- * @subcrq - first TX descriptor
- * @hdr_field - bit field determining which headers will be sent
+ * @skb: socket buffer
+ * @num_entries: number of descriptors to be sent
+ * @subcrq: first TX descriptor
+ * @hdr_field: bit field determining which headers will be sent
  *
  * This function will build a TX descriptor array with applicable
  * L2/L3/L4 packet header descriptors to be sent by send_subcrq_indirect.
@@ -1997,7 +1997,7 @@  static int do_change_param_reset(struct ibmvnic_adapter *adapter,
 	return 0;
 }
 
-/**
+/*
  * do_reset returns zero if we are able to keep processing reset events, or
  * non-zero if we hit a fatal error and must halt.
  */
diff --git a/drivers/net/xen-netfront.c b/drivers/net/xen-netfront.c
index 920cac4385bf7..93740ef4cf1b4 100644
--- a/drivers/net/xen-netfront.c
+++ b/drivers/net/xen-netfront.c
@@ -1582,7 +1582,7 @@  static struct net_device *xennet_create_dev(struct xenbus_device *dev)
 	return ERR_PTR(err);
 }
 
-/**
+/*
  * Entry point to this code when a new device is created.  Allocate the basic
  * structures and the ring buffers for communication with the backend, and
  * inform the backend of the appropriate details for those.
@@ -1659,7 +1659,7 @@  static void xennet_disconnect_backend(struct netfront_info *info)
 	}
 }
 
-/**
+/*
  * We are reconnecting to the backend, due to a suspend/resume, or a backend
  * driver restart.  We tear down our netif structure and recreate it, but
  * leave the device-layer structures intact so that this is transparent to the
@@ -2305,7 +2305,7 @@  static int xennet_connect(struct net_device *dev)
 	return 0;
 }
 
-/**
+/*
  * Callback received when the backend's state changes.
  */
 static void netback_changed(struct xenbus_device *dev,