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

[Akira Yokosawa]

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

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