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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250310155301.6db5033c@foz.lan>
Date: Mon, 10 Mar 2025 15:53:01 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Viresh Kumar <viresh.kumar@...aro.org>
Cc: Rasmus Villemoes <linux@...musvillemoes.dk>, Yury Norov
 <yury.norov@...il.com>, Vincent Guittot <vincent.guittot@...aro.org>, Akira
 Yokosawa <akiyks@...il.com>, linux-doc@...r.kernel.org, Jonathan Corbet
 <corbet@....net>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in
 cpumask.h

Em Fri,  7 Mar 2025 13:04:51 +0530
Viresh Kumar <viresh.kumar@...aro.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@...aro.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 *@...p1 & *@...p2

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 & *@...3

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