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
>
