Re: [PATCH 1/5] scripts/kernel-doc: teach kdoc about QLIST_ macros

[Peter Maydell <peter.maydell@linaro.org>]

On Fri, 8 Mar 2024 at 08:49, Thomas Huth <thuth@redhat.com> wrote:
>
> On 08/03/2024 09.22, Peter Xu wrote:
> > On Fri, Mar 08, 2024 at 08:09:15AM +0000, Alex Bennée wrote:
> >> Peter Xu <peterx@redhat.com> writes:
> >>
> >>> On Thu, Mar 07, 2024 at 06:11:01PM +0000, Alex Bennée wrote:
> >>>> The kernel-doc script does some pre-processing on structure
> >>>> definitions before parsing for names. Teach it about QLIST and replace
> >>>> with simplified structures representing the base type.
> >>>>
> >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >>>> ---
> >>>>   scripts/kernel-doc | 9 ++++++++-
> >>>>   1 file changed, 8 insertions(+), 1 deletion(-)
> >>>>
> >>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> >>>> index 240923d509a..26c47562e79 100755
> >>>> --- a/scripts/kernel-doc
> >>>> +++ b/scripts/kernel-doc
> >>>> @@ -1226,7 +1226,14 @@ sub dump_struct($$) {
> >>>>    # replace DECLARE_KFIFO_PTR
> >>>>    $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
> >>>>
> >>>> -  my $declaration = $members;
> >>>> +        # QEMU Specific Macros
> >>>> +
> >>>> +        # replace QLIST_ENTRY with base type and variable name
> >>>> +        $members =~ s/QLIST_ENTRY\(([^)]+)\)\s+([^;]+)/$1 \*$2/gos;
> >>>> +        # replace QLIST_HEAD, optionally capturing an anonymous struct marker, and capture type and variable name
> >>>> +        $members =~ s/QLIST_HEAD\(\s*,\s*([^)]+)\)\s+([^;]+)/struct { $1 *lh_first; } $2/gos;
> >>>> +
> >>>> +        my $declaration = $members;
> >>>
> >>> May need a "tabify" here..
> >>
> >> Ugg that file is a mess. Any idea what we should use for perl, tabs or
> >> spaces? I can update editorconfig.
> >
> > Indeed.. not perl expert here.
> >
> > For this one it might be still good to keep the same with the code around
> > before an attempt to clean it up.
>
> I think this file originate from the Linux kernel repo, so it might be a
> good idea to keep it in sync with the version from there?

Yes; we should avoid divergence where we can. We already
have one script (checkpatch) that has diverged too far
for easy resyncing, it would be good to avoid this one
going in the same direction. We last did a resync in 2020.

thanks
-- PMM