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
