On 12/29/2017 06:28 PM, Mauro Carvalho Chehab wrote:
> Em Fri, 29 Dec 2017 18:17:08 -0800
> Randy Dunlap <rdun...@infradead.org> 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
That (copy-and-pasted to prevent typos) gives me 304 (i.e., one less).
> 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.
There are definitely missing parameter descriptions that are not being
reported in linux-next. Here's one such example (still working in
linux-next-20171222, just with differing versions of scripts/kernel-doc).
kernel-doc from 4.15-rc5:
../net/core/dev.c:6400: warning: No description found for parameter 'extack'
../net/core/dev.c:6423: warning: No description found for parameter 'extack'
kernel-doc from linux-next-20171222:
{those reports are missing but the descriptions are also missing}
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
