Messages in this thread | | | Date | Mon, 5 Oct 2020 12:51:11 +0200 | From | Mauro Carvalho Chehab <> | Subject | Re: [PATCH 00/14] get rid of the remaining kernel-doc warnings when building the docs |
| |
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
| |