Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 28 Oct 2021 08:03:31 +0100
From:   Mauro Carvalho Chehab <mchehab@kernel.org>
To:     Marc Zyngier <maz@kernel.org>
Cc:     Stephen Rothwell <sfr@canb.auug.org.au>,
        Linus Walleij <linus.walleij@linaro.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Joey Gouly <joey.gouly@arm.com>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Linux Next Mailing List <linux-next@vger.kernel.org>
Subject: Re: linux-next: build warning after merge of the pinctrl tree
Message-ID: <20211028080331.6d199082@sal.lan>
In-Reply-To: <874k92bu4q.wl-maz@kernel.org>
References: <20211027220118.71a229ab@canb.auug.org.au>
        <874k92bu4q.wl-maz@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

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