Em Thu, 1 Oct 2020 15:41:00 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Wed, 30 Sep 2020 15:24:27 +0200 > Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote: > > > With Sphinx 3.x, the ".. c:type:" tag was changed to accept either: > > > > .. c:type:: typedef-like declaration > > .. c:type:: name > > > > Using it for other types (including functions) don't work anymore. > > > > So, there are newer tags for macro, enum, struct, union, and others, > > which doesn't exist on older versions. > > > > Add a check for the Sphinx version and change the produced tags > > accordingly. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> > > --- > > scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++---- > > 1 file changed, 65 insertions(+), 6 deletions(-) > > So this seems generally good, but I do wonder if we shouldn't just pass > the sphinx version into kernel-doc as a parameter? We're already doing a > version check in the makefile, we should be able to capture the result and > pass it in, maybe? My plan is to work later on a patch adding support for it ;) Yet, there's something to consider: troubleshooting. I mean, if a warning is produced during "make htmldocs", as part of troubleshooting, people do: ./scripts/kernel-doc <some file> It sounds more natural that, by default, it will output the same output as the one generated via "make htmldocs". So, the version detection code there sounds the right way for doing it. Yet, as you pointed, as kerneldoc.py knows the Sphinx version, it should be easy for it to pass an argument and avoid version detection, by calling kernel-doc as: ./scripts/kernel-doc --sphinx3 <somefile> or ./scripts/kernel-doc --sphinx-version 3 <somefile> (not sure yet about how to name such arguments ;-) ) That might give some performance gain. Btw, with regards to performance, I have a few other ideas that might help how to improve kernel-doc (yet to be verified). At least for now, I opted to keep it more straight without adding more complexity. My plan is to work on those things after the merge window. Thanks, Mauro
