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: <bcce7d39-f142-4838-ba23-4fa2dda69fd0@gmail.com>
Date: Tue, 11 Mar 2025 00:27:47 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Rasmus Villemoes <linux@...musvillemoes.dk>,
 Yury Norov <yury.norov@...il.com>,
 Vincent Guittot <vincent.guittot@...aro.org>, linux-doc@...r.kernel.org,
 Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org,
 Viresh Kumar <viresh.kumar@...aro.org>, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

Hi,

Mauro Carvalho Chehab wrote:
> Em Fri,  7 Mar 2025 13:04:51 +0530
[...]
>>  /**
>> - * cpumask_first_and - return the first cpu from *srcp1 & *srcp2
>> + * cpumask_first_and - return the first cpu from *@...p1 & *@...p2
> 
> I don't think this would produce the right output. See my other comment.
> 
> See, if I add this there:
> 
> 	 * cpumask_first_and - return the first cpu from ``*srcp1`` & @srcp2 & *@...3
> 
> The kernel-doc output is:
> 
> 	.. c:function:: unsigned int cpumask_first_and (const struct cpumask *srcp1, const struct cpumask *srcp2)
> 
> 	   return the first cpu from ``*srcp1`` & **srcp2** & ***srp3**
> 
> e.g.:
> 
> - srcp1: will not be bold, but it will use a monospaced font and will have 
> 	 an asterisk;
> 
> - srcp2: will be bold, without asterisk;
> 
> - srcp3: violates ReST spec: different versions may show it different
>          and warnings may be issued.

This third pattern is available since commit 69fc23efc7e5 ("kernel-doc:
Add unary operator * to $type_param_ref") and I haven't heard of any
regression report.

Sphinx parses ***srp3** in the following way:

  - It sees the first ** and start strong emphasis.
  - It continues that mode until it sees next **.

In the end, Sphinx will produce strongly emphasized "*srp3".

It would be much better to convert *@...3 into "\*\ **srp3", which will
result in normal "*" followed by emphasized "srp3", but I didn't go that
far at that time.  This looked sufficient to me as a band-aid workaround.

Or you are aware of any Sphinx version who doesn't work in this way?

        Thanks, Akira