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
