Messages in this thread | | | Date | Thu, 28 Oct 2021 08:03:31 +0100 | From | Mauro Carvalho Chehab <> | Subject | Re: linux-next: build warning after merge of the pinctrl tree |
| |
Em Wed, 27 Oct 2021 12:10:45 +0100 Marc Zyngier <maz@kernel.org> escreveu:
> On Wed, 27 Oct 2021 12:01:18 +0100, > Stephen Rothwell <sfr@canb.auug.org.au> wrote: > > > > Hi all, > > > > After merging the pinctrl tree, today's linux-next build (htmldocs) > > produced this warning: > > > > include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip' > > > > Introduced by commit > > > > cfe6807d82e9 ("gpio: Allow per-parent interrupt data") > > > > But may actually be a problem with the tool :-( > > I guess the tool doesn't like having two fields that are part of a > union documented together... Happy to tweak it if someone tells me how > this should be written.
Yes, that's the case. See, when you do:
/** * @parent_handler_data: * @parent_handler_data_array: * * Data associated, and passed to, the handler for the parent * interrupt. Can either be a single pointer if @per_parent_data * is false, or an array of @num_parents pointers otherwise. If * @per_parent_data is true, @parent_handler_data_array cannot be * NULL. */ union { void *parent_handler_data; void **parent_handler_data_array; };
The tool will understand it as an undocumented "parent_handler_data" and a documented "parent_handler_data_array".
It has to do that, as otherwise it won't get cases where people just adds a @foo: as a template but actually forgets to fill it.
The solution would be to add a description for both, e. g. something similar to:
/** * @parent_handler_data: * * If @per_parent_data is false, contains a single pointer * with the data associated, and passed to, the handler for the * parent interrupt. * * @parent_handler_data_array: * * If @per_parent_data is true, it should contain an array of * @num_parents pointers with the data associated, and passed to, * the handler for the parent interrupt. Cannot be NULL. */
Regards, Mauro
| |