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 for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20250310165638.7b001393@sal.lan>
Date: Mon, 10 Mar 2025 16:56:38 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Akira Yokosawa <akiyks@...il.com>
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>
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

Em Tue, 11 Mar 2025 00:27:47 +0900
Akira Yokosawa <akiyks@...il.com> escreveu:

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

Yes, I got it. But, as "*" is a reserved symbol, used already as
*italic* and **bold**, nothing prevents some day to have a ***something***.

Also, other ReST tools may misinterpret that,as, IMO, this has
undefined behavior. So, better avoid that.

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

Yeah, either that or **\*srp3** to keep the asterisk bold
(assuming it works properly) [1].

[1] I remember I had some troubles with escape codes on
bold before, but can't rename exactly on what version.

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

Didn't check this specific issue.

> 
>         Thanks, Akira
>