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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri,  7 Mar 2025 13:04:51 +0530
Viresh Kumar <viresh.kumar@linaro.org> 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@linaro.org>
> ---
>  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