[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <20250317092403.uphmlx7u52ntvih5@vireshk-i7>
Date: Mon, 17 Mar 2025 14:54:03 +0530
From: Viresh Kumar <viresh.kumar@...aro.org>
To: Yury Norov <yury.norov@...il.com>, Akira Yokosawa <akiyks@...il.com>,
Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Rasmus Villemoes <linux@...musvillemoes.dk>,
Vincent Guittot <vincent.guittot@...aro.org>,
linux-doc@...r.kernel.org, Jonathan Corbet <corbet@....net>,
linux-kernel@...r.kernel.org
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
cpumask.h
Hi Yury / Akira / Mauro,
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.
I was looking to get a public links to cpumask APIs, like:
https://docs.kernel.org/core-api/kernel-api.html#bitmap-operations
which I can use from the (WIP) Rust cpumask documentation.
Can you suggest how do I move ahead with this ?
- Let the warnings be there and keep the comment as "... cpu in *src1p & *stc2p" ?
- Something like what Mauro suggested: "... cpu in @src1p and @stc2p" ?
- Something else ?
--
viresh
Powered by blists - more mailing lists