Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h

[Mauro Carvalho Chehab]

Em Tue, 11 Mar 2025 00:27:47 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> 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 *@srcp1 & *@srcp2  
> > 
> > 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 & *@srp3
> > 
> > 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 *@srp3 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
>