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;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Andy Shevchenko <andy.shevchenko@gmail.com>
Cc:     Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Linux Documentation List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: Re: anonymous enums in kernel doc
In-Reply-To: <CAHp75Vc0SwC=WxUOiokUik1G4uPE6bHfX_F_ckgp-eEJaVuWhA@mail.gmail.com>
References: <CAHp75VfpnGEZcnrQLFYaFQ-HuxTmPw5OnewKmRGfXQf__ztjww@mail.gmail.com>
 <87r1lgx8fo.fsf@meer.lwn.net>
 <CAHp75Vc0SwC=WxUOiokUik1G4uPE6bHfX_F_ckgp-eEJaVuWhA@mail.gmail.com>
Date:   Tue, 16 Feb 2021 10:05:39 -0700
Message-ID: <87mtw4x7rw.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Andy Shevchenko <andy.shevchenko@gmail.com> writes:

> On Tue, Feb 16, 2021 at 6:51 PM Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> > Mauro, can you do some test cases in your workflow against anonymous
>> > enum in ernel doc, please?
>> >
>> > They are broken again, please fix the script!
>> >
>> > drivers/pinctrl/intel/pinctrl-intel.c:204: warning: wrong kernel-doc
>> > identifier on line:
>> > * enum - Locking variants of the pad configuration
>> >
>> > Above is simply a wrong statement.
>>
>> The real problem, perhaps, is that there seems to be little point in
>> adding kerneldoc comments for anonymous enums; where are you going to
>> use that documentation?
>
> I had been explicitly told during review (IIRC by maintainers) to make
> it such, while the initial version was exactly like you are thinking
> of. So, I'm not the right person to be asked :-)
>
>>  The error message could perhaps be changed to
>> say that; meanwhile, perhaps this one could be fixed with an action like
>> s%/**%/*% ?
>
> See above. I think regression comes from the kernel doc script,
> earlier it was okay. That said, the author of kernel doc changes has
> to submit a patch to amend the driver and maintainers will review it.

kerneldoc now warns about various incorrect things that it used to just
silently pass over.  There is no regression here, just a new diagnostic
to point out something that was never going to work right.  Unless you
have a good idea for what kerneldoc should do with a block like that?

(An alternative fix, of course, would be to give the enum a name so it
can actually be used for type checking.)

Thanks,

jon