Em Tue, 22 Sep 2020 10:56:56 -0600 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Tue, 22 Sep 2020 10:23:46 +0300 > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote: > > > > Should we be converting the kernel-doc script to output 3.0-style markup > > > for structs? > > > > IIUC it's not backwards compatible with Sphinx pre-3.0, so you'd either > > have to require Sphinx 3.0 or have kernel-doc emit both, depending on > > the Sphinx version. > > Certainly before requiring 3.0 we should, like, actually make it work with > 3.0... People with time to do that appear to be rather scarce at the > moment, though. I'll get to it eventually but I have a few other things > on my plate as well. Tried to build now with Sphinx 3.2.1. There are thousands of warnings: build succeeded, 3423 warnings. Like those: Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/workqueue'. Declaration is 'unsigned long delay'. And those: ./include/uapi/linux/firewire-cdev.h:38: WARNING: Type must be either just a name or a typedef-like declaration. If just a name: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6] struct fw_cdev_event_iso_interrupt ------^ If typedef-like declaration: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name. [error at 34] struct fw_cdev_event_iso_interrupt ----------------------------------^ If I'm not mistaken, one of the reasons why cdomain was added is due to the duplicate C declaration. - I guess changing kernel-doc to produce Sphinx 3.x syntax and raise the bar requiring 3.0 to be the minimal version would be one alternative, but this won't solve the duplicated C declarations. Does Sphinx 3.x have some way to enable "local" C references? Another one could be to make cdomain compatible with 3.x and make it handle the differences. Not sure how easy/hard would be to do that. Thanks, Mauro
