On 12/30/2017 05:39 AM, Mauro Carvalho Chehab wrote: > Em Fri, 29 Dec 2017 20:12:15 -0800 > Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu: > >> On 12/29/2017 06:28 PM, Mauro Carvalho Chehab wrote: >>> 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 >> >> 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 majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html