Messages in this thread | | | Subject | Re: [PATCH] s390/crypto: fix all kernel-doc warnings in vfio_ap_ops.c | From | Randy Dunlap <> | Date | Fri, 6 Aug 2021 18:38:32 -0700 |
| |
On 8/6/21 6:26 AM, Tony Krowiak wrote: > Reviewed-by: Tony Krowiak <akrowiak@linux.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@infradead.org> >> Reported-by: kernel test robot <lkp@intel.com> >> Cc: Jason Gunthorpe <jgg@nvidia.com> >> Cc: Tony Krowiak <akrowiak@linux.ibm.com> >> Cc: Halil Pasic <pasic@linux.ibm.com> >> Cc: Jason Herne <jjherne@linux.ibm.com> >> Cc: Harald Freudenberger <freude@linux.ibm.com> >> Cc: linux-s390@vger.kernel.org >> --- >> drivers/s390/crypto/vfio_ap_ops.c | 116 ++++++++++++---------------- >> 1 file changed, 52 insertions(+), 64 deletions(-)
-- ~Randy
| |