Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Oscar Carter <oscar.carter@gmx.com>
To:     Forest Bond <forest@alittletooquiet.net>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc:     Oscar Carter <oscar.carter@gmx.com>,
        Quentin Deslandes <quentin.deslandes@itdev.co.uk>,
        Malcolm Priestley <tvboxspy@gmail.com>,
        Amir Mahdi Ghorbanian <indigoomega021@gmail.com>,
        Stefano Brivio <sbrivio@redhat.com>,
        "John B. Wyatt IV" <jbwyatt4@gmail.com>,
        Colin Ian King <colin.king@canonical.com>,
        Dan Carpenter <dan.carpenter@oracle.com>,
        devel@driverdev.osuosl.org, linux-kernel@vger.kernel.org
Subject: [PATCH 2/2] staging: vt6656: Fix functions' documentation
Date:   Sat, 18 Apr 2020 14:36:59 +0200
Message-Id: <20200418123659.4475-3-oscar.carter@gmx.com>
In-Reply-To: <20200418123659.4475-1-oscar.carter@gmx.com>
References: <20200418123659.4475-1-oscar.carter@gmx.com>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Replace the functions' documentation by the kernel-doc style fixing the
parameters and return value.

Signed-off-by: Oscar Carter <oscar.carter@gmx.com>
=2D--
 drivers/staging/vt6656/card.c  | 101 +++++++++++----------------------
 drivers/staging/vt6656/mac.c   |  67 ++++++++--------------
 drivers/staging/vt6656/power.c |  12 ++--
 3 files changed, 61 insertions(+), 119 deletions(-)

diff --git a/drivers/staging/vt6656/card.c b/drivers/staging/vt6656/card.c
index 99ad56b7617d..51acf2212577 100644
=2D-- a/drivers/staging/vt6656/card.c
+++ b/drivers/staging/vt6656/card.c
@@ -46,15 +46,12 @@ static const u16 cw_rxbcntsf_off[MAX_RATE] =3D {
 	192, 96, 34, 17, 34, 23, 17, 11, 8, 5, 4, 3
 };

-/*
- * Description: Set NIC media channel
+/**
+ * vnt_set_channel - Set NIC media channel.
+ * @priv: The adapter to be set.
+ * @connection_channel: The channel to be set.
  *
- * Parameters:
- *  In:
- *      pDevice             - The adapter to be set
- *      connection_channel  - Channel to be set
- *  Out:
- *      none
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_set_channel(struct vnt_private *priv, u32 connection_channel)
 {
@@ -99,19 +96,13 @@ static const u8 vnt_rspinf_gb_table[] =3D {
 	0x0e, 0x8d, 0x0a, 0x88, 0x0a, 0x8c, 0x0a, 0x8c, 0x0a
 };

-/*
- * Description: Set RSPINF
- *
- * Parameters:
- *  In:
- *      pDevice             - The adapter to be set
- *  Out:
- *      none
- *
- * Return Value: None.
+/**
+ * vnt_set_rspinf - Set RSPINF.
+ * @priv: The adapter to be set.
+ * @bb_type: The base band type.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
-
 int vnt_set_rspinf(struct vnt_private *priv, u8 bb_type)
 {
 	const u8 *data;
@@ -145,17 +136,11 @@ int vnt_set_rspinf(struct vnt_private *priv, u8 bb_t=
ype)
 			       MESSAGE_REQUEST_MACREG, len, data);
 }

-/*
- * Description: Update IFS
- *
- * Parameters:
- *  In:
- *	priv - The adapter to be set
- * Out:
- *	none
- *
- * Return Value: None.
+/**
+ * vnt_update_ifs - Update IFS.
+ * @priv: The adapter to be set.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_update_ifs(struct vnt_private *priv)
 {
@@ -300,20 +285,14 @@ u64 vnt_get_tsf_offset(u8 rx_rate, u64 tsf1, u64 tsf=
2)
 	return tsf1 - tsf2 - (u64)cw_rxbcntsf_off[rx_rate % MAX_RATE];
 }

-/*
- * Description: Sync. TSF counter to BSS
- *              Get TSF offset and write to HW
- *
- * Parameters:
- *  In:
- *      priv		- The adapter to be sync.
- *      time_stamp	- Rx BCN's TSF
- *      local_tsf	- Local TSF
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_adjust_tsf - Sync TSF counter to BSS. Get TSF offset and write to =
HW.
+ * @priv: The adapter to be set.
+ * @rx_rate: The Rx rate.
+ * @time_stamp: The Rx BCN's TSF.
+ * @local_tsf: The local TSF.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_adjust_tsf(struct vnt_private *priv, u8 rx_rate,
 		   u64 time_stamp, u64 local_tsf)
@@ -408,19 +387,13 @@ u64 vnt_get_next_tbtt(u64 tsf, u16 beacon_interval)
 	return tsf;
 }

-/*
- * Description: Set NIC TSF counter for first Beacon time
- *              Get NEXTTBTT from adjusted TSF and Beacon Interval
- *
- * Parameters:
- *  In:
- *      dwIoBase        - IO Base
- *	beacon_interval - Beacon Interval
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_reset_next_tbtt - Set NIC TSF counter for first beacon time. Get
+ *			 NEXTTBTT from adjusted TSF and beacon interval.
+ * @priv: The adapter to be set.
+ * @beacon_interval: The beacon interval.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_reset_next_tbtt(struct vnt_private *priv, u16 beacon_interval)
 {
@@ -444,20 +417,14 @@ int vnt_reset_next_tbtt(struct vnt_private *priv, u1=
6 beacon_interval)
 			       MESSAGE_REQUEST_TBTT, 0, 8, data);
 }

-/*
- * Description: Sync NIC TSF counter for Beacon time
- *              Get NEXTTBTT and write to HW
- *
- * Parameters:
- *  In:
- *	priv		- The adapter to be set
- *      tsf		- Current TSF counter
- *      beacon_interval - Beacon Interval
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_update_next_tbtt - Sync NIC TSF counter for beacon time. Get NEXTT=
BTT
+ *			  and write to HW.
+ * @priv: The adapter to be set.
+ * @tsf: The current TSF counter.
+ * @beacon_interval: The beacon interval.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_update_next_tbtt(struct vnt_private *priv, u64 tsf,
 			 u16 beacon_interval)
diff --git a/drivers/staging/vt6656/mac.c b/drivers/staging/vt6656/mac.c
index 639172fad0f3..c4b541178109 100644
=2D-- a/drivers/staging/vt6656/mac.c
+++ b/drivers/staging/vt6656/mac.c
@@ -22,18 +22,12 @@
 #include "mac.h"
 #include "usbpipe.h"

-/*
- * Description:
- *      Write MAC Multicast Address Mask
- *
- * Parameters:
- *  In:
- *	mc_filter (mac filter)
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_mac_set_filter - Write MAC multicast address mask.
+ * @priv: The adapter to be set.
+ * @mc_filter: The mac filter.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_mac_set_filter(struct vnt_private *priv, u64 mc_filter)
 {
@@ -44,16 +38,11 @@ int vnt_mac_set_filter(struct vnt_private *priv, u64 m=
c_filter)
 			       (u8 *)&le_mc);
 }

-/*
- * Description:
- *      Shut Down MAC
- *
- * Parameters:
- *  In:
- *  Out:
- *      none
- *
+/**
+ * vnt_mac_shutdown - Shut down MAC.
+ * @priv: The adapter to be set.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_mac_shutdown(struct vnt_private *priv)
 {
@@ -72,19 +61,12 @@ int vnt_mac_set_bb_type(struct vnt_private *priv, u8 t=
ype)
 			       data);
 }

-/*
- * Description:
- *      Disable the Key Entry by MISCFIFO
- *
- * Parameters:
- *  In:
- *      dwIoBase        - Base Address for MAC
- *
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_mac_disable_keyentry - Disable the key entry by MISCFIFO.
+ * @priv: The adapter to be set.
+ * @entry_idx: The entry index.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_mac_disable_keyentry(struct vnt_private *priv, u8 entry_idx)
 {
@@ -92,19 +74,16 @@ int vnt_mac_disable_keyentry(struct vnt_private *priv,=
 u8 entry_idx)
 			       sizeof(entry_idx), &entry_idx);
 }

-/*
- * Description:
- *      Set the Key by MISCFIFO
- *
- * Parameters:
- *  In:
- *      dwIoBase        - Base Address for MAC
- *
- *  Out:
- *      none
- *
- * Return Value: none
+/**
+ * vnt_mac_set_keyentry - Set the key by MISCFIFO.
+ * @priv: The adapter to be set.
+ * @key_ctl: The key control.
+ * @entry_idx: The entry index.
+ * @key_idx: The key index.
+ * @addr: The ethernet address.
+ * @key: The key.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
 int vnt_mac_set_keyentry(struct vnt_private *priv, u16 key_ctl, u32 entry=
_idx,
 			 u32 key_idx, u8 *addr, u8 *key)
diff --git a/drivers/staging/vt6656/power.c b/drivers/staging/vt6656/power=
.c
index 2d8d5a332a63..cca50c9f4087 100644
=2D-- a/drivers/staging/vt6656/power.c
+++ b/drivers/staging/vt6656/power.c
@@ -77,16 +77,12 @@ void vnt_enable_power_saving(struct vnt_private *priv,=
 u16 listen_interval)
 	dev_dbg(&priv->usb->dev,  "PS:Power Saving Mode Enable...\n");
 }

-/*
- *
- * Routine Description:
- * Disable hw power saving functions
- *
- * Return Value:
- *    None.
+/**
+ * vnt_disable_power_saving - Disable hw power saving functions.
+ * @priv: The adapter to be set.
  *
+ * Return: 0 if successful, or a negative error code on failure.
  */
-
 int vnt_disable_power_saving(struct vnt_private *priv)
 {
 	int ret;
=2D-
2.20.1