On 07-03-25, 12:05, Yury Norov wrote: > On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote: > > /** > > - * 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. Jonathan / Akira, can you please answer this one ? > > @@ -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? Without this we get: "ERROR: Unexpected indentation", for the last line of the code block that contains: " ...". The double-colon creates a code-block for the below code and gets rid of the warning. > > > /** > > - * cpumask_weight - Count of bits in *srcp > > + * cpumask_weight - Count of bits in *@srcp > > * @srcp: the cpumask to count bits (< nr_cpu_ids) in. > > Here nr_cpu_ids is also a variable. Why you don't prefix it with @? I was only looking to fix the build warnings / errors for now, and did not look into detail for such issues. Yes, it should be marked with @. I will try to go through all the comments now and fix such issues. -- viresh
