netdev - Re: [PATCH v3 12/17] wifi: cc33xx: Add scan.c, scan.h

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20241102120030.GG1838431@kernel.org>
Date: Sat, 2 Nov 2024 12:00:30 +0000
From: Simon Horman <horms@...nel.org>
To: "Nemanov, Michael" <michael.nemanov@...com>
Cc: Kalle Valo <kvalo@...nel.org>, "David S. Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>, linux-wireless@...r.kernel.org,
	netdev@...r.kernel.org, devicetree@...r.kernel.org,
	linux-kernel@...r.kernel.org, Sabeeh Khan <sabeeh-khan@...com>
Subject: Re: [PATCH v3 12/17] wifi: cc33xx: Add scan.c, scan.h

On Mon, Oct 28, 2024 at 06:26:50PM +0200, Nemanov, Michael wrote:
> On 8/9/2024 7:03 PM, Simon Horman wrote:
> > On Tue, Aug 06, 2024 at 08:00:13PM +0300, Michael Nemanov wrote:
> > 
> > ...
> > 
> > > diff --git a/drivers/net/wireless/ti/cc33xx/scan.h b/drivers/net/wireless/ti/cc33xx/scan.h
> > 
> > ...
> > 
> > > +/**
> > > + * struct cc33xx_cmd_ssid_list - scan SSID list description
> > > + *
> > > + * @role_id:            roleID
> > > + *
> > > + * @num_of_ssids:       Number of SSID in the list. MAX 16 entries
> > 
> > @num_of_ssids -> @n_ssids
> > 
> > > + *
> > > + * @ssid_list:          SSIDs to scan for (active scan only)
> > 
> > @ssid_list -> @ssids
> >
> 
> Thanks for the feedback, will fix.
> 
> > Please document all non-private fields,
> > and annotate those that are private.
> > 
> 
> Not sure I follow. You mean mark private vs. non private members in the
> documentation? If so, private to what (the CC33xx driver or the underlying
> HW)?

Hi Michael,

I'm not sure why I mentioned private, perhaps it was a general statement
that all fields should either be documented or marked as private. If
you don't think anything is private - whatever that might mean - then you
can ignore that part of my comment. But suffice to say, there is syntax to
mark fields as private[1].

[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#members

> > There are a number of similar minor Kernel doc problems with this patch.
> > Please consider using W=1 builds or ./scripts/kernel-doc -none
> > (bonus points for -Wall)
> > 
> 
> Ran both, got warning for "no structured comments found" on multiple files.
> Is that it?

I'm a but unsure why you see that, but what I was referring to is this:

$ ./scripts/kernel-doc -none drivers/net/wireless/ti/cc33xx/scan.h
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Function parameter or struct member 'header' not described in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Function parameter or struct member 'scan_type' not described in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Function parameter or struct member 'n_ssids' not described in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Function parameter or struct member 'ssids' not described in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Function parameter or struct member 'padding' not described in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Excess struct member 'num_of_ssids' description in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:104: warning: Excess struct member 'ssid_list' description in 'cc33xx_cmd_ssid_list'
drivers/net/wireless/ti/cc33xx/scan.h:149: warning: bad line:
drivers/net/wireless/ti/cc33xx/scan.h:177: warning: cannot understand function prototype: 'struct sched_scan_plan_cmd '
drivers/net/wireless/ti/cc33xx/scan.h:227: warning: Function parameter or struct member 'u' not described in 'scan_param'
drivers/net/wireless/ti/cc33xx/scan.h:227: warning: Excess struct member 'one_shot' description in 'scan_param'
drivers/net/wireless/ti/cc33xx/scan.h:227: warning: Excess struct member 'periodic' description in 'scan_param'
drivers/net/wireless/ti/cc33xx/scan.h:269: warning: Function parameter or struct member 'header' not described in 'cc33xx_cmd_scan_params'
drivers/net/wireless/ti/cc33xx/scan.h:269: warning: Function parameter or struct member 'padding' not described in 'cc33xx_cmd_scan_params'
drivers/net/wireless/ti/cc33xx/scan.h:295: warning: Function parameter or struct member 'header' not described in 'cc33xx_cmd_set_ies'
drivers/net/wireless/ti/cc33xx/scan.h:319: warning: Function parameter or struct member 'header' not described in 'cc33xx_cmd_scan_stop'
drivers/net/wireless/ti/cc33xx/scan.h:319: warning: Function parameter or struct member 'padding' not described in 'cc33xx_cmd_scan_stop'