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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Mon, 10 Mar 2025 08:07:06 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Yury Norov <yury.norov@gmail.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 *@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  

IMO, the better would be to use:

	cpumask_next_and - get the next cpu in @src1p and @src2p

e. g. I would avoid the asterisk and the "&" symbol at the comment - the
less symbols we have there, the better for people reading the C code.

> > 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.

Please notice that, if we use:

	/**
	 * cpumask_first_and - return the first cpu from *srcp1 & @srcp2
	 */

The ReST output from kernel-doc is:

	.. c:function:: unsigned int cpumask_first_and (const struct cpumask *srcp1, const struct cpumask *srcp2)

	   return the first cpu from *srcp1 & **srcp2**

Placing an asterisk before "@" won't work, as, in order to produce a 
valid ReST syntax, the output for srcp2 would need to be be: 

	**\*srcp2**

Please notice that I didn't test if the above would work on Sphinx. 
I remember we had some issues with things similar to that in the past,
with older versions of the toolchain. So, we need first to test it
against minimal and current versions of toolchain to be sure that this
would work.

Assuming that the above works, we'll need to define how this
will be represented at the source code. IMO, neither @*var nor *@var
would be great. Perhaps we could stick with *var, but then we would
need to ensure that this won't cause any regressions with already
existing kernel-doc macros.

Thanks,
Mauro