On 12/30/2017 05:39 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 29 Dec 2017 20:12:15 -0800
> Randy Dunlap <rdun...@infradead.org> escreveu:
>
>> 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}
>
> Hmm... here, it showed it:
>
> $ git checkout next-20171221
Please try it with linux-next-20171222 instead of 1221.
It has many more patches to scripts/kernel-doc.
> $ make SPHINXDIRS=networking htmldocs
> SPHINX htmldocs -->
> file:///devel/v4l/linux-next/Documentation/output/networking
> PARSE include/uapi/linux/dvb/audio.h
> PARSE include/uapi/linux/dvb/ca.h
> PARSE include/uapi/linux/dvb/dmx.h
> PARSE include/uapi/linux/dvb/frontend.h
> PARSE include/uapi/linux/dvb/net.h
> PARSE include/uapi/linux/dvb/video.h
> PARSE include/uapi/linux/videodev2.h
> PARSE include/uapi/linux/media.h
> PARSE include/uapi/linux/cec.h
> PARSE include/uapi/linux/lirc.h
> Running Sphinx v1.4.9
> making output directory...
> load additional sphinx-config:
> /devel/v4l/linux-next/Documentation/networking/conf.py
> loading pickled environment... not yet created
> building [mo]: targets for 0 po files that are out of date
> building [html]: targets for 5 source files that are out of date
> updating environment: 5 added, 0 changed, 0 removed
> ./net/core/dev.c:1695: warning: Excess function parameter 'dev' description
> in 'call_netdevice_notifiers_info'
> ./net/core/dev.c:6398: warning: No description found for parameter 'extack'
> ./net/core/dev.c:6421: warning: No description found for parameter 'extack'
> ./include/linux/phylink.h:56: warning: No description found for parameter
> '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising'
> ./include/linux/phylink.h:56: warning: No description found for parameter
> '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising'
> ./include/linux/phylink.h:56: warning: Excess struct member 'advertising'
> description in 'phylink_link_state'
> ./include/linux/phylink.h:56: warning: Excess struct member 'lp_advertising'
> description in 'phylink_link_state'
> ./drivers/net/phy/sfp-bus.c:430: warning: No description found for parameter
> 'fwnode'
> ./drivers/net/phy/sfp-bus.c:430: warning: Excess function parameter 'np'
> description in 'sfp_register_upstream'
> ./drivers/net/phy/sfp-bus.c:430: warning: No description found for parameter
> 'fwnode'
> ./drivers/net/phy/sfp-bus.c:430: warning: Excess function parameter 'np'
> description in 'sfp_register_upstream'
> reading sources... [100%] z8530book
>
> ./net/core/dev.c:4519: ERROR: Unknown target name: "page_is".
> looking for now-outdated files... none found
> pickling environment... done
> checking consistency...
> /devel/v4l/linux-next/Documentation/networking/msg_zerocopy.rst:: WARNING:
> document isn't included in any toctree
> done
> preparing documents... done
> writing output... [100%] z8530book
>
> generating indices... genindex
> writing additional pages... search
> copying static files... done
> copying extra files... done
> dumping search index in English (code: en) ... done
> dumping object inventory... done
> build succeeded, 2 warnings.
--
~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
