Message-ID: <662656aa-c25b-4f83-8131-eb39a6a42917@gmail.com>
Date: Mon, 10 Mar 2025 18:11:41 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Viresh Kumar <viresh.kumar@...aro.org>, 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, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

Hi,

Viresh Kumar wrote:
> 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?

That is not impossible, I would say.

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

I was not around when transition to Sphinx was made in 2016, and I don't
know much of kernel-doc (or its predecessor doc-book) comment format.

So below is my wild guesses.

Current Documentation/doc-guide/kernel-doc.rst has no mention of "*" WRT
where it is allowed or disallowed, which results in occasional complaints
from Sphinx on unmatched start/end of emphasis.

However, the use of "*" is indicated for itemized list, which directly
employs reST format.

It doesn't say anything about literal/code blocks, either.

So I have to say that current kernel-doc has quite a few of undefined
things on reST output.

kernel-doc in python3 might help untangle the mess.

This all need some consensus on kenrel-doc behavior to be reached, and
update/enhance of kernel-doc (script).

So my suggestion would be to hold these changes for the time being.

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

Provided the brokenness of kernel-doc spec & script, I think you can
wait until it is properly fixed/enhanced.

The problem is: Is there somebody who would be interested enough to do
such an improvement?

        Thanks, Akira

Powered by blists - more mailing lists