Em Fri, 7 Mar 2025 13:04:51 +0530
Viresh Kumar <viresh.kumar@xxxxxxxxxx> escreveu:
> This fixes various kernel-doc formatting errors in cpumask.h:
>
> - WARNING: Inline literal start-string without end-string.
> - ERROR: Unexpected indentation.
> - ERROR: Unknown target name: "gfp".
>
> Signed-off-by: Viresh Kumar <viresh.kumar@xxxxxxxxxx>
> ---
> include/linux/cpumask.h | 65 +++++++++++++++++++++--------------------
> 1 file changed, 34 insertions(+), 31 deletions(-)
>
> diff --git a/include/linux/cpumask.h b/include/linux/cpumask.h
> index 36a890d0dd57..8b53e01dbd97 100644
> --- a/include/linux/cpumask.h
> +++ b/include/linux/cpumask.h
> @@ -20,7 +20,7 @@
> * cpumask_pr_args - printf args to output a cpumask
> * @maskp: cpumask to be printed
> *
> - * Can be used to provide arguments for '%*pb[l]' when printing a cpumask.
> + * Can be used to provide arguments for '%*pb [l]' when printing a cpumask.
The best here would be to use, instead:
* Can be used to provide arguments for ``*pb[l]`` when printing a cpumask.
Which would be converted to this ReST notation:
Can be used to provide arguments for ``*pb[l]`` when printing a cpumask.
which is what it would be expected when converted to html/pdf.
> */
> #define cpumask_pr_args(maskp) nr_cpu_ids, cpumask_bits(maskp)
>
> @@ -166,7 +166,7 @@ static __always_inline unsigned int cpumask_first_zero(const struct cpumask *src
> }
>
> /**
> - * 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.
Thanks,
Mauro
