netdev - Re: [PATCH] ath: wil6210: fix a bunch of kernel-doc warnings

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] [day] [month] [year] [list]

Message-ID: <2c849887-ce85-4f1a-b180-5f29211aa625@infradead.org>
Date: Fri, 21 Nov 2025 21:26:08 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Simon Horman <horms@...nel.org>
Cc: netdev@...r.kernel.org, Johannes Berg <johannes@...solutions.net>,
 linux-wireless@...r.kernel.org
Subject: Re: [PATCH] ath: wil6210: fix a bunch of kernel-doc warnings



On 11/21/25 5:04 AM, Simon Horman wrote:
> On Sun, Nov 16, 2025 at 06:02:13PM -0800, Randy Dunlap wrote:
>> scripts/kernel-doc.py reports 51 kernel-doc warnings in wil6210.h.
>> Fix all kernel-doc warnings reported in wil6210.h.
>>
>> Several comments are changed from "/**" to "/*" since it appears that
>> "/**" was used for many non-kernel-doc comments.
>>
>> - add kernel-doc for missing function parameters
>> - add one function "Returns:"
>> - correct kernel-doc struct name to match actual struct name in 2 places
>>
>> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> 
> ...
> 
>> @@ -444,8 +444,7 @@ static inline u8 mk_cidxtid(u8 cid, u8 t
>>   * parse_cidxtid - parse @cidxtid field
>>   * @cid: store CID value here
>>   * @tid: store TID value here
>> - *
>> - * @cidxtid field encoded as bits 0..3 - CID; 4..7 - TID
>> + * @cidxtid: field encoded as bits 0..3 - CID; 4..7 - TID
> 
> Hi Randy,
> 
> I wonder if it would make sense to move the @cidxtid line
> so it is above the @cid line. In which case the order of
> the documentation of the parameters would match their order
> in the subject.

I've looked at a lot of kernel-doc comments. I prefer in-order
comments, but so many of them are out of order that I don't bother
with them.

> But either way, this patch looks good to me.
> 
> Reviewed-by: Simon Horman <horms@...nel.org>
> 
>>   */
>>  static inline void parse_cidxtid(u8 cidxtid, u8 *cid, u8 *tid)
>>  {
> 
> ...
> 

thanks.
-- 
~Randy