netdev - Re: [PATCH] ptp: ptp_clockmatrix: repair non-kernel-doc comment

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]

Date:   Wed, 10 Nov 2021 18:09:20 -0800
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Jakub Kicinski <kuba@...nel.org>
Cc:     netdev@...r.kernel.org, kernel test robot <lkp@...el.com>,
        Min Li <min.li.xe@...esas.com>,
        Richard Cochran <richardcochran@...il.com>,
        "David S. Miller" <davem@...emloft.net>
Subject: Re: [PATCH] ptp: ptp_clockmatrix: repair non-kernel-doc comment

On 11/10/21 5:49 PM, Jakub Kicinski wrote:
> On Wed, 10 Nov 2021 14:53:06 -0800 Randy Dunlap wrote:
>> Do not use "/**" to begin a comment that is not in kernel-doc format.
>>
>> Prevents this docs build warning:
>>
>> drivers/ptp/ptp_clockmatrix.c:1679: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>      * Maximum absolute value for write phase offset in picoseconds
>>
>> Fixes: 794c3dffacc16 ("ptp: ptp_clockmatrix: Add support for FW 5.2 (8A34005)")
>> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
>> Reported-by: kernel test robot <lkp@...el.com>
>> Cc: Min Li <min.li.xe@...esas.com>
>> Cc: Richard Cochran <richardcochran@...il.com>
>> Cc: "David S. Miller" <davem@...emloft.net>
>> Cc: Jakub Kicinski <kuba@...nel.org>
>> ---
>>   drivers/ptp/ptp_clockmatrix.c |    2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> --- linux-next-20211110.orig/drivers/ptp/ptp_clockmatrix.c
>> +++ linux-next-20211110/drivers/ptp/ptp_clockmatrix.c
>> @@ -1699,7 +1699,7 @@ static int initialize_dco_operating_mode
>>   
>>   /* PTP Hardware Clock interface */
>>   
>> -/**
>> +/*
>>    * Maximum absolute value for write phase offset in picoseconds
>>    *
>>    * @channel:  channel
> 
> Looks like it documents parameters to the function, should we either
> fix it to make it valid kdoc or remove the params (which TBH aren't
> really adding much value)?
> 

a. It would be the only kernel-doc in that source file and
b. we usually want to document exported or at least non-static
functions and don't try very hard to document static ones.

I don't care much about whether we remove the other comments
that are there...
If you want them removed, I can do that.

-- 
~Randy