On Wed, 26 Aug 2020, merez@codeaurora.org wrote:

On 2020-08-21 10:16, Lee Jones wrote:

quoted

Fixes the following W=1 kernel build warning(s):

 drivers/net/wireless/ath/wil6210/wmi.c:52: warning: Incorrect use of
kernel-doc format:  * Addressing - theory of operations
 drivers/net/wireless/ath/wil6210/wmi.c:70: warning: Incorrect use of
kernel-doc format:  * @sparrow_fw_mapping provides memory remapping
table for sparrow
 drivers/net/wireless/ath/wil6210/wmi.c:80: warning: cannot understand
function prototype: 'const struct fw_map sparrow_fw_mapping[] = '
 drivers/net/wireless/ath/wil6210/wmi.c:107: warning: Cannot
understand  * @sparrow_d0_mac_rgf_ext - mac_rgf_ext section for
Sparrow D0
 drivers/net/wireless/ath/wil6210/wmi.c:115: warning: Cannot
understand  * @talyn_fw_mapping provides memory remapping table for
Talyn
 drivers/net/wireless/ath/wil6210/wmi.c:158: warning: Cannot
understand  * @talyn_mb_fw_mapping provides memory remapping table for
Talyn-MB
 drivers/net/wireless/ath/wil6210/wmi.c:236: warning: Function
parameter or member 'x' not described in 'wmi_addr_remap'
 drivers/net/wireless/ath/wil6210/wmi.c:255: warning: Function
parameter or member 'section' not described in 'wil_find_fw_mapping'
 drivers/net/wireless/ath/wil6210/wmi.c:278: warning: Function
parameter or member 'wil' not described in 'wmi_buffer_block'
 drivers/net/wireless/ath/wil6210/wmi.c:278: warning: Function
parameter or member 'ptr_' not described in 'wmi_buffer_block'
 drivers/net/wireless/ath/wil6210/wmi.c:278: warning: Function
parameter or member 'size' not described in 'wmi_buffer_block'
 drivers/net/wireless/ath/wil6210/wmi.c:307: warning: Function
parameter or member 'wil' not described in 'wmi_addr'
 drivers/net/wireless/ath/wil6210/wmi.c:307: warning: Function
parameter or member 'ptr' not described in 'wmi_addr'
 drivers/net/wireless/ath/wil6210/wmi.c:1589: warning: Function
parameter or member 'wil' not described in 'wil_find_cid_ringid_sta'
 drivers/net/wireless/ath/wil6210/wmi.c:1589: warning: Function
parameter or member 'vif' not described in 'wil_find_cid_ringid_sta'
 drivers/net/wireless/ath/wil6210/wmi.c:1589: warning: Function
parameter or member 'cid' not described in 'wil_find_cid_ringid_sta'
 drivers/net/wireless/ath/wil6210/wmi.c:1589: warning: Function
parameter or member 'ringid' not described in
'wil_find_cid_ringid_sta'
 drivers/net/wireless/ath/wil6210/wmi.c:1876: warning: Function
parameter or member 'vif' not described in 'wmi_evt_ignore'
 drivers/net/wireless/ath/wil6210/wmi.c:1876: warning: Function
parameter or member 'id' not described in 'wmi_evt_ignore'
 drivers/net/wireless/ath/wil6210/wmi.c:1876: warning: Function
parameter or member 'd' not described in 'wmi_evt_ignore'
 drivers/net/wireless/ath/wil6210/wmi.c:1876: warning: Function
parameter or member 'len' not described in 'wmi_evt_ignore'
 drivers/net/wireless/ath/wil6210/wmi.c:2588: warning: Function
parameter or member 'wil' not described in 'wmi_rxon'

Cc: Maya Erez <redacted>
Cc: Kalle Valo <redacted>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: linux-wireless@vger.kernel.org
Cc: wil6210@qti.qualcomm.com
Cc: netdev@vger.kernel.org
Signed-off-by: Lee Jones <redacted>
---
 drivers/net/wireless/ath/wil6210/wmi.c | 28 ++++++++++++++------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/drivers/net/wireless/ath/wil6210/wmi.c

b/drivers/net/wireless/ath/wil6210/wmi.c
index c7136ce567eea..3a6ee85acf6c7 100644

--- a/drivers/net/wireless/ath/wil6210/wmi.c
+++ b/drivers/net/wireless/ath/wil6210/wmi.c

@@ -31,7 +31,7 @@ MODULE_PARM_DESC(led_id,
 #define WIL_WAIT_FOR_SUSPEND_RESUME_COMP 200
 #define WIL_WMI_PCP_STOP_TO_MS 5000

-/**
+/*
  * WMI event receiving - theory of operations
  *
  * When firmware about to report WMI event, it fills memory area

The correct format for such documentation blocks is:
/**
 * DOC: Theory of Operation

This comment is also applicable for the rest of such documentation blocks
changed in this patch.

Ah yes, good point.  Will fix.

quoted

@@ -66,7 +66,7 @@ MODULE_PARM_DESC(led_id,
  * AHB address must be used.
  */

-/**
+/*
  * @sparrow_fw_mapping provides memory remapping table for sparrow
  *
  * array size should be in sync with the declaration in the wil6210.h

For files in net/ and drivers/net/ the preferred style for long (multi-line)
comments is a different and
the text should be in the same line as /*, as follows:
/* sparrow_fw_mapping provides memory remapping table for sparrow
I would also remove the @ from @sparrow_fw_mapping.
This comment is also applicable for the rest of such documentation blocks
changed in this patch.

Sounds fair.  Will also fix.

Thank you.

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