Em Thu, 10 Sep 2020 19:12:08 +0100
Matthew Wilcox <willy@xxxxxxxxxxxxx> 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
