linux-kernel - Re: [PATCH] s390/crypto: fix all kernel-doc warnings in vfio_ap

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:   Fri, 6 Aug 2021 18:38:32 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Tony Krowiak <akrowiak@...ux.ibm.com>,
        linux-kernel@...r.kernel.org, kbuild-all@...ts.01.org
Cc:     kernel test robot <lkp@...el.com>,
        Jason Gunthorpe <jgg@...dia.com>,
        Halil Pasic <pasic@...ux.ibm.com>,
        Jason Herne <jjherne@...ux.ibm.com>,
        Harald Freudenberger <freude@...ux.ibm.com>,
        linux-s390@...r.kernel.org
Subject: Re: [PATCH] s390/crypto: fix all kernel-doc warnings in vfio_ap_ops.c

On 8/6/21 6:26 AM, Tony Krowiak wrote:
> Reviewed-by: Tony Krowiak <akrowiak@...ux.ibm.com>
> 
> Pardon my ignorance, but this is the first I've seen of kernel-doc warnings.
> Is there a flag I can set when I build to get kernel-doc warnings? Is there a tool I can run?
> Where is the kernel-doc format documented? I'd like to avoid this in the future.

Hi,

Here is the 0day bot report:
https://lore.kernel.org/lkml/202108010650.DLRzJOtm-lkp@intel.com/
(not sent to any of your group, sadly).

kernel-doc format is documented in Documentation/doc-guide/kernel-doc.rst.

The 0day bot lists the reproduction steps. It used clang but I used
gcc. Shouldn't matter in this case. The main point from the 0day bot
is that "this is a W=1 build".  Using W=1 causes checks for extra
C compiler warnings and also it causes checks for documentation build
errors/warnings.

In your build environment, using "make W=1 ARCH=s390 allmodconfig all"
will produce lots of output (both compiler and kernel-doc output).
I suppose that is the expected way to do it.

AFAIK there is no support for something like "make W=1 htmldocs"
to just check for kernel-doc errors/warnings in source files, so what
I do when I am targeting only one source file is something like what
is documented in the file referenced above:

"Running the ``kernel-doc`` tool with increased verbosity and without actual
output generation may be used to verify proper formatting of the
documentation comments. For example::

	scripts/kernel-doc -v -none drivers/foo/bar.c
"
and then I script that for ease of use.
Using the latter command reports lots more kernel-doc warnings than
the 0day bot reported, so I fixed all of them that it found.


HTH.


> On 8/6/21 1:01 AM, Randy Dunlap wrote:
>> The 0day bot reported some kernel-doc warnings in this file so clean up
>> all of the kernel-doc and use proper kernel-doc formatting.
>> There are no more kernel-doc errors or warnings reported in this file.
>>
>> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
>> Reported-by: kernel test robot <lkp@...el.com>
>> Cc: Jason Gunthorpe <jgg@...dia.com>
>> Cc: Tony Krowiak <akrowiak@...ux.ibm.com>
>> Cc: Halil Pasic <pasic@...ux.ibm.com>
>> Cc: Jason Herne <jjherne@...ux.ibm.com>
>> Cc: Harald Freudenberger <freude@...ux.ibm.com>
>> Cc: linux-s390@...r.kernel.org
>> ---
>>   drivers/s390/crypto/vfio_ap_ops.c |  116 ++++++++++++----------------
>>   1 file changed, 52 insertions(+), 64 deletions(-)


-- 
~Randy