Em Wed, 27 Oct 2021 12:10:45 +0100
Marc Zyngier <maz@xxxxxxxxxx> escreveu:
> On Wed, 27 Oct 2021 12:01:18 +0100,
> Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> 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
