Re: [PATCH 00/14] get rid of the remaining kernel-doc warnings when building the docs

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 10 Sep 2020 19:12:08 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> On Thu, Sep 10, 2020 at 12:23:53PM +0200, Mauro Carvalho Chehab wrote:
> > As described on its subject, this series finally get rid of all kernel-doc warnings.
> > 
> > With this series applied (plus my last series fixing other warnings), building
> > the docs is now clean[1] against next-20200909:  
> 
> Thanks, this has been a truly heroic effort.
> 
> I'd suggest that we change the kernel build to always run the CHKDOC
> instead of at W=1 (or rather, as the patch I just sent out demonstrates,
> not at all (oops)).  Otherwise you're just going to have to continue
> doing this.

It sounds a good idea for me to run kernel-doc with W=1 - or even
better - with allyesconfig/allmodconfig (no matter if W=0/W=1/W=2).

> At some point, perhaps we can add some other warnings at W=1, like
> an EXPORT_SYMBOL of a function which doesn't have kernel-doc.

Makes sense, but I suspect that supporting it is not too trivial.

I mean, a script checking for EXPORT_SYMBOL* should check not
only the C file, but also the included header files, as the
kernel-doc markup can be on one of its includes. 

An enhanced version of something like this:

</script>
#!/usr/bin/perl

my $file = shift or die "Need a file name";

my @files;
my @exports;

my $dir = $file;
$dir =~ s,[^\/]+$,,;

push @files, $file;
open IN, "<$file";
while (<IN>) {
	push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/);
	push @files, "include/$1" if (m/^\s*#\s*include\s+[\<](\S+)[\>]/);
	push @files, "$dir/$1" if (m/^\s*#\s*include\s+[\"](\S+)[\"]/);
}
close IN;

my $doc;

foreach my $i (@files) {
	$doc .= qx(./scripts/kernel-doc $i 2>/dev/null);
}

foreach my $e (@exports) {
	print "$e doesn't have kernel-doc markups\n" if (!($doc =~ m/\b$e\b/));
}
</script>

On simple cases, the above script helps to check what's missing:

	$ ./check_exports drivers/acpi/acpi_lpat.c
	<nothing returned>
	$ ./test drivers/media/v4l2-core/v4l2-common.c 
	__v4l2_find_nearest_size doesn't have kernel-doc markups
	v4l2_apply_frmsize_constraints doesn't have kernel-doc markups
	v4l2_fill_pixfmt_mp doesn't have kernel-doc markups
	v4l2_fill_pixfmt doesn't have kernel-doc markups

Yet, it the actual script will also need to handle some special
cases:

- it should check if the Makefile used by the file has a "-I" directive.
  This could be tricky, due to Makefile recursion.
- it should also check if there is a kernel-doc entry for such header.
  a "git grep" could be used in this case.
- It should also handle the optional arguments of kernel-doc, like
  :internal", :external", ":no-identifiers", "identifiers", as it is
  possible that there is a kernel-doc entry, but this is excluded
  by a kernel-doc modifier.
- It should also check if the exported symbol is a function,
  in order to exclude static vars that are exported.

I suspect that there are several other border cases.

Thanks,
Mauro