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: <20250310061540.zpfyisvchyua2cuv@vireshk-i7>
Date: Mon, 10 Mar 2025 11:45:40 +0530
From: Viresh Kumar <viresh.kumar@...aro.org>
To: Akira Yokosawa <akiyks@...il.com>, Jonathan Corbet <corbet@....net>,
	Yury Norov <yury.norov@...il.com>
Cc: Rasmus Villemoes <linux@...musvillemoes.dk>,
	Vincent Guittot <vincent.guittot@...aro.org>,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

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

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 *@...p
> >   * @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