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
$ 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.
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
