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

[Jonathan Corbet]

Yury Norov <yury.norov@xxxxxxxxx> 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 *@srcp1 & *@srcp2 & *@srcp3
>>   * @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 *@src1p & *@src2p
>>   * @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