linux-kernel - Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87r0350yk5.fsf@trenco.lwn.net>
Date: Mon, 10 Mar 2025 08:07:06 -0600
From: Jonathan Corbet <corbet@....net>
To: Yury Norov <yury.norov@...il.com>, Viresh Kumar <viresh.kumar@...aro.org>
Cc: Rasmus Villemoes <linux@...musvillemoes.dk>, Vincent Guittot
 <vincent.guittot@...aro.org>, Akira Yokosawa <akiyks@...il.com>,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Mauro Carvalho
 Chehab <mchehab@...nel.org>
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

Yury Norov <yury.norov@...il.com> writes:

> On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
>>  /**
>> - * cpumask_first_and_and - return the first cpu from *srcp1 & *srcp2 & *srcp3
>> + * cpumask_first_and_and - return the first cpu from *@...p1 & *@...p2 & *@...p3
>>   * @srcp1: the first input
>>   * @srcp2: the second input
>>   * @srcp3: the third input
>> @@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);
>>  #endif /* NR_CPUS */
>>  
>>  /**
>> - * cpumask_next_and - get the next cpu in *src1p & *src2p
>> + * cpumask_next_and - get the next cpu in *@...1p & *@...2p
>>   * @n: the cpu prior to the place to search (i.e. return will be > @n)
>>   * @src1p: the first cpumask pointer
>>   * @src2p: the second cpumask pointer
>
> So the question: if some word in this particular comment block is
> prefixed with @ symbol, can we teach kernel-doc to consider every
> occurrence of this word as a variable?
>
> Why I'm asking: before the "*src1p & *src2p" was a line of C code.
> And because we are all C programmers here, it's really simple to ident
> it and decode. After it looks like something weird, and I think many
> of us will just mentally skip it.
>
> I like kernel-docs and everything, but again, kernel sources should
> stay readable, and particularly comments should stay human-readable.

I'm sure it *can* be done, yes.  In truth, given that we're dealing with
named parameters in a prototype that we are decoding, we might be able,
with enough clever programming, to do away with that markup entirely.

It's just a matter of programming :)

I've added Mauro, since he's in the process of replacing kernel-doc
entirely.  I suspect he has enough on his hands at the moment without
adding extra objectives, and will want to get that replacement
successfully done first.  But it's a worthy goal to keep in mind.


>> @@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>>   * @mask1: the first cpumask pointer
>>   * @mask2: the second cpumask pointer
>>   *
>> - * This saves a temporary CPU mask in many places.  It is equivalent to:
>> + * This saves a temporary CPU mask in many places.  It is equivalent to::
>> + *
>
> I'm OK with extra line, but this double-colon. What for and what does
> it mean?

The :: introduces a literal block, which needs a blank line to start it.

Thanks,

jon