Em Fri, 29 Dec 2017 18:17:08 -0800
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> In linux-next-20171222, this message:
>
> print STDERR "${file}:$.: warning:" .
> " No description found for parameter '$param'\n";
>
> has roughly/approximately been replaced with:
>
> print STDERR
> "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
>
>
> Using linux-next-20171222, with its ("new") scripts/kernel-doc, I see
>
> > grep -c not.described doc005.out
> 86
>
> but if I use scripts/kernel-doc from linux-4.15-rc5 (in linux-next-20171222), I see
>
> > grep -c No.description.found doc006.out
> 305
>
>
> This is not good.
Actually, if you look at the messages produced before linux-next, you'll
notice that the *same* error is reported multiple times.
The problem is that some headers are included multiple times:
$ git grep include/net/cfg80211.h Documentation/|wc -l
111
If you look inside Documentation/driver-api/80211/cfg80211.rst,
you'll see:
.. kernel-doc:: include/net/cfg80211.h
:functions: ieee80211_channel_flags
.. kernel-doc:: include/net/cfg80211.h
:functions: ieee80211_channel
...
With the old incarnation of kernel-doc, every time it parses an
script, it generate warnings for all symbols, *including* the
ones that aren't part of the kernel-doc output. The one at
linux-next has an extra logic that, when "functions" is used,
it will only output warnings for the symbol mentioned there,
with prevents it to repeat the same error report every time.
I suspect that, if you do:
grep No.description.found doc006.out|sort|uniq|wc -l
you'll see that the number of errors on 4.15-rc5 is actually
smaller than on linux-next, as it now reports missing symbols
on nested structs and unions.
Regards,
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
