Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields

From: Sakari Ailus <sakari.ailus@linux.intel.com>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: Ricardo Ribalda <ribalda@chromium.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Tiffany Lin <tiffany.lin@mediatek.com>,
	Andrew-CT Chen <andrew-ct.chen@mediatek.com>,
	Yunfei Dong <yunfei.dong@mediatek.com>,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	Matthias Brugger <matthias.bgg@gmail.com>,
	AngeloGioacchino Del Regno
	<angelogioacchino.delregno@collabora.com>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Hans Verkuil <hverkuil@xs4all.nl>,
	Kieran Bingham <kieran.bingham@ideasonboard.com>,
	Bin Liu <bin.liu@mediatek.com>,
	Ezequiel Garcia <ezequiel@vanguardiasur.com.ar>,
	Philipp Zabel <p.zabel@pengutronix.de>,
	Stanimir Varbanov <stanimir.k.varbanov@gmail.com>,
	Vikash Garodia <quic_vgarodia@quicinc.com>,
	Bryan O 'Donoghue <bryan.odonoghue@linaro.org>,
	Bjorn Andersson <andersson@kernel.org>,
	Konrad Dybcio <konrad.dybcio@linaro.org>,
	Sylwester Nawrocki <s.nawrocki@samsung.com>,
	Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>,
	Alim Akhtar <alim.akhtar@samsung.com>,
	Marek Szyprowski <m.szyprowski@samsung.com>,
	Andrzej Hajda <andrzej.hajda@intel.com>,
	Bingbu Cao <bingbu.cao@intel.com>,
	Tianshu Qiu <tian.shu.qiu@intel.com>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Neil Armstrong <neil.armstrong@linaro.org>,
	Kevin Hilman <khilman@baylibre.com>,
	Jerome Brunet <jbrunet@baylibre.com>,
	Martin Blumenstingl <martin.blumenstingl@googlemail.com>,
	linux-doc@vger.kernel.org
Subject: Re: [RFC 1/1] kernel-doc: Support arrays of pointers struct fields
Date: Sat, 27 Jan 2024 22:41:02 +0000	[thread overview]
Message-ID: <ZbWGfgHoZgDyXDNn@kekkonen.localdomain> (raw)
In-Reply-To: <aa94772b-7010-4bba-b099-d3b8fe1b97aa@infradead.org>

Hi Randy,

On Sat, Jan 27, 2024 at 01:01:01PM -0800, Randy Dunlap wrote:
> Hi Sakari,
> 
> On 1/27/24 10:53, Sakari Ailus wrote:
> > In a rather unusual arrangement in include/media/v4l2-vp9.h struct
> > v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
> > pointer to an array, which is what's usually done.
> > 
> 
> Yet another kernel-doc bug. I have a list of 5 or 6 or 8 bugs that are
> similar to this one, but I didn't have this one.

:-)

Regular expressions are not best for parsing C. It seems to be doable in
practice but imperfect at the same time.

> 
> 
> > Add support for such arrays of pointers to kernel-doc.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> 
> 
> Did this work for you?
> I still see the same warnings as before this patch is applied.

Hmm. How did you test this? I did:

	$ scripts/kernel-doc include/media/v4l2-vp9.h > /dev/null

Without this patch I do get a bunch of errors, with this patch there's no
output. The produced kernel-doc seemed to be fine, too (with the
redirection removed).

> 
> 
> > ---
> > Hi Ricardo,
> > 
> > I tried to ram it together with processing the rest but it seemed
> > to complicate processing the usual fields.
> > 
> >  scripts/kernel-doc | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index e8aefd258a29..728b1ffc0478 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1509,6 +1509,15 @@ sub create_parameterlist($$$$) {
> >  	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> >  	    save_struct_actual($param);
> >  	    push_parameter($param, $type, $arg, $file, $declaration_name);
> > +	} elsif ($arg =~ m/\(.+\)\s*\[/) {
> > +	    # array-of-pointers
> > +	    $arg =~ tr/#/,/;
> > +	    $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
> > +	    $param = $1;
> > +	    $type = $arg;
> > +	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> > +	    save_struct_actual($param);
> > +	    push_parameter($param, $type, $arg, $file, $declaration_name);
> >  	} elsif ($arg) {
> >  	    $arg =~ s/\s*:\s*/:/g;
> >  	    $arg =~ s/\s*\[/\[/g;
> 
> 
> Thanks.

-- 
Regards,

Sakari Ailus