[PATCH V2 0/2] docs: core-api: Update kernel-api.rst to include cpumask.h

[PATCH V2 0/2] docs: core-api: Update kernel-api.rst to include cpumask.h

[Viresh Kumar]

Hello,

This includes cpumask.h in kernel-api.rst and fixes some kernel-doc formatting
warnings/errors.

V2:
- Don't escape *, use @ instead before argument name.
- Don't escape %, use space before "[".
- Use "::" instead of fancy code-blocks.

Viresh Kumar (2):
  cpumask: Fix kernel-doc formatting errors in cpumask.h
  docs: core-api: Update kernel-api.rst to include cpumask.h

 Documentation/core-api/kernel-api.rst |  6 +++
 include/linux/cpumask.h               | 65 ++++++++++++++-------------
 2 files changed, 40 insertions(+), 31 deletions(-)

-- 
2.31.1.272.g89b43f80a514

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

[Viresh Kumar]

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.
  */
 #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
  * @srcp1: the first input
  * @srcp2: the second input
  *
@@ -179,7 +179,7 @@ unsigned int cpumask_first_and(const struct cpumask *srcp1, const struct cpumask
 }
 
 /**
- * cpumask_first_and_and - return the first cpu from *srcp1 & *srcp2 & *srcp3
+ * cpumask_first_and_and - return the first cpu from *@srcp1 & *@srcp2 & *@srcp3
  * @srcp1: the first input
  * @srcp2: the second input
  * @srcp3: the third input
@@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);
 #endif /* NR_CPUS */
 
 /**
- * cpumask_next_and - get the next cpu in *src1p & *src2p
+ * cpumask_next_and - get the next cpu in *@src1p & *@src2p
  * @n: the cpu prior to the place to search (i.e. return will be > @n)
  * @src1p: the first cpumask pointer
  * @src2p: the second cpumask pointer
@@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
  * @mask1: the first cpumask pointer
  * @mask2: the second cpumask pointer
  *
- * This saves a temporary CPU mask in many places.  It is equivalent to:
+ * This saves a temporary CPU mask in many places.  It is equivalent to::
+ *
  *	struct cpumask tmp;
  *	cpumask_and(&tmp, &mask1, &mask2);
  *	for_each_cpu(cpu, &tmp)
@@ -352,7 +353,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
  * @mask1: the first cpumask pointer
  * @mask2: the second cpumask pointer
  *
- * This saves a temporary CPU mask in many places.  It is equivalent to:
+ * This saves a temporary CPU mask in many places.  It is equivalent to::
+ *
  *	struct cpumask tmp;
  *	cpumask_andnot(&tmp, &mask1, &mask2);
  *	for_each_cpu(cpu, &tmp)
@@ -369,7 +371,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
  * @mask1: the first cpumask pointer
  * @mask2: the second cpumask pointer
  *
- * This saves a temporary CPU mask in many places.  It is equivalent to:
+ * This saves a temporary CPU mask in many places.  It is equivalent to::
+ *
  *	struct cpumask tmp;
  *	cpumask_or(&tmp, &mask1, &mask2);
  *	for_each_cpu(cpu, &tmp)
@@ -411,7 +414,7 @@ unsigned int cpumask_any_but(const struct cpumask *mask, unsigned int cpu)
 }
 
 /**
- * cpumask_any_and_but - pick an arbitrary cpu from *mask1 & *mask2, but not this one.
+ * cpumask_any_and_but - pick an arbitrary cpu from *@mask1 & *@mask2, but not this one.
  * @mask1: the first input cpumask
  * @mask2: the second input cpumask
  * @cpu: the cpu to ignore
@@ -545,7 +548,7 @@ static __always_inline void __cpumask_clear_cpu(int cpu, struct cpumask *dstp)
  * cpumask_assign_cpu - assign a cpu in a cpumask
  * @cpu: cpu number (< nr_cpu_ids)
  * @dstp: the cpumask pointer
- * @bool: the value to assign
+ * @value: the value to assign
  */
 static __always_inline void cpumask_assign_cpu(int cpu, struct cpumask *dstp, bool value)
 {
@@ -623,7 +626,7 @@ static __always_inline void cpumask_clear(struct cpumask *dstp)
 }
 
 /**
- * cpumask_and - *dstp = *src1p & *src2p
+ * cpumask_and - *@dstp = *@src1p & *@src2p
  * @dstp: the cpumask result
  * @src1p: the first input
  * @src2p: the second input
@@ -639,7 +642,7 @@ bool cpumask_and(struct cpumask *dstp, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_or - *dstp = *src1p | *src2p
+ * cpumask_or - *@dstp = *@src1p | *@src2p
  * @dstp: the cpumask result
  * @src1p: the first input
  * @src2p: the second input
@@ -653,7 +656,7 @@ void cpumask_or(struct cpumask *dstp, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_xor - *dstp = *src1p ^ *src2p
+ * cpumask_xor - *@dstp = *@src1p ^ *@src2p
  * @dstp: the cpumask result
  * @src1p: the first input
  * @src2p: the second input
@@ -667,7 +670,7 @@ void cpumask_xor(struct cpumask *dstp, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_andnot - *dstp = *src1p & ~*src2p
+ * cpumask_andnot - *@dstp = *@src1p & ~*@src2p
  * @dstp: the cpumask result
  * @src1p: the first input
  * @src2p: the second input
@@ -683,7 +686,7 @@ bool cpumask_andnot(struct cpumask *dstp, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_equal - *src1p == *src2p
+ * cpumask_equal - *@src1p == *@src2p
  * @src1p: the first input
  * @src2p: the second input
  *
@@ -697,7 +700,7 @@ bool cpumask_equal(const struct cpumask *src1p, const struct cpumask *src2p)
 }
 
 /**
- * cpumask_or_equal - *src1p | *src2p == *src3p
+ * cpumask_or_equal - *@src1p | *@src2p == *@src3p
  * @src1p: the first input
  * @src2p: the second input
  * @src3p: the third input
@@ -714,7 +717,7 @@ bool cpumask_or_equal(const struct cpumask *src1p, const struct cpumask *src2p,
 }
 
 /**
- * cpumask_intersects - (*src1p & *src2p) != 0
+ * cpumask_intersects - (*@src1p & *@src2p) != 0
  * @src1p: the first input
  * @src2p: the second input
  *
@@ -729,7 +732,7 @@ bool cpumask_intersects(const struct cpumask *src1p, const struct cpumask *src2p
 }
 
 /**
- * cpumask_subset - (*src1p & ~*src2p) == 0
+ * cpumask_subset - (*@src1p & ~*@src2p) == 0
  * @src1p: the first input
  * @src2p: the second input
  *
@@ -743,7 +746,7 @@ bool cpumask_subset(const struct cpumask *src1p, const struct cpumask *src2p)
 }
 
 /**
- * cpumask_empty - *srcp == 0
+ * cpumask_empty - *@srcp == 0
  * @srcp: the cpumask to that all cpus < nr_cpu_ids are clear.
  *
  * Return: true if srcp is empty (has no bits set), else false
@@ -754,7 +757,7 @@ static __always_inline bool cpumask_empty(const struct cpumask *srcp)
 }
 
 /**
- * cpumask_full - *srcp == 0xFFFFFFFF...
+ * cpumask_full - *@srcp == 0xFFFFFFFF...
  * @srcp: the cpumask to that all cpus < nr_cpu_ids are set.
  *
  * Return: true if srcp is full (has all bits set), else false
@@ -765,10 +768,10 @@ static __always_inline bool cpumask_full(const struct cpumask *srcp)
 }
 
 /**
- * cpumask_weight - Count of bits in *srcp
+ * cpumask_weight - Count of bits in *@srcp
  * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
  *
- * Return: count of bits set in *srcp
+ * Return: count of bits set in *@srcp
  */
 static __always_inline unsigned int cpumask_weight(const struct cpumask *srcp)
 {
@@ -776,11 +779,11 @@ static __always_inline unsigned int cpumask_weight(const struct cpumask *srcp)
 }
 
 /**
- * cpumask_weight_and - Count of bits in (*srcp1 & *srcp2)
+ * cpumask_weight_and - Count of bits in (*@srcp1 & *@srcp2)
  * @srcp1: the cpumask to count bits (< nr_cpu_ids) in.
  * @srcp2: the cpumask to count bits (< nr_cpu_ids) in.
  *
- * Return: count of bits set in both *srcp1 and *srcp2
+ * Return: count of bits set in both *@srcp1 and *@srcp2
  */
 static __always_inline
 unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumask *srcp2)
@@ -789,11 +792,11 @@ unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumas
 }
 
 /**
- * cpumask_weight_andnot - Count of bits in (*srcp1 & ~*srcp2)
+ * cpumask_weight_andnot - Count of bits in (*@srcp1 & ~*@srcp2)
  * @srcp1: the cpumask to count bits (< nr_cpu_ids) in.
  * @srcp2: the cpumask to count bits (< nr_cpu_ids) in.
  *
- * Return: count of bits set in both *srcp1 and *srcp2
+ * Return: count of bits set in both *@srcp1 and *@srcp2
  */
 static __always_inline
 unsigned int cpumask_weight_andnot(const struct cpumask *srcp1,
@@ -803,7 +806,7 @@ unsigned int cpumask_weight_andnot(const struct cpumask *srcp1,
 }
 
 /**
- * cpumask_shift_right - *dstp = *srcp >> n
+ * cpumask_shift_right - *@dstp = *@srcp >> n
  * @dstp: the cpumask result
  * @srcp: the input to shift
  * @n: the number of bits to shift by
@@ -816,7 +819,7 @@ void cpumask_shift_right(struct cpumask *dstp, const struct cpumask *srcp, int n
 }
 
 /**
- * cpumask_shift_left - *dstp = *srcp << n
+ * cpumask_shift_left - *@dstp = *@srcp << n
  * @dstp: the cpumask result
  * @srcp: the input to shift
  * @n: the number of bits to shift by
@@ -829,7 +832,7 @@ void cpumask_shift_left(struct cpumask *dstp, const struct cpumask *srcp, int n)
 }
 
 /**
- * cpumask_copy - *dstp = *srcp
+ * cpumask_copy - *@dstp = *@srcp
  * @dstp: the result
  * @srcp: the input cpumask
  */
@@ -840,7 +843,7 @@ void cpumask_copy(struct cpumask *dstp, const struct cpumask *srcp)
 }
 
 /**
- * cpumask_any - pick an arbitrary cpu from *srcp
+ * cpumask_any - pick an arbitrary cpu from *@srcp
  * @srcp: the input cpumask
  *
  * Return: >= nr_cpu_ids if no cpus set.
@@ -848,7 +851,7 @@ void cpumask_copy(struct cpumask *dstp, const struct cpumask *srcp)
 #define cpumask_any(srcp) cpumask_first(srcp)
 
 /**
- * cpumask_any_and - pick an arbitrary cpu from *mask1 & *mask2
+ * cpumask_any_and - pick an arbitrary cpu from *@mask1 & *@mask2
  * @mask1: the first input cpumask
  * @mask2: the second input cpumask
  *
@@ -941,7 +944,7 @@ bool zalloc_cpumask_var_node(cpumask_var_t *mask, gfp_t flags, int node)
 /**
  * alloc_cpumask_var - allocate a struct cpumask
  * @mask: pointer to cpumask_var_t where the cpumask is returned
- * @flags: GFP_ flags
+ * @flags: %GFP_ flags
  *
  * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
  * a nop returning a constant 1 (in <linux/cpumask.h>).
-- 
2.31.1.272.g89b43f80a514

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

[Akira Yokosawa]

Hi,

Only a couple of minor nits.

Viresh Kumar wrote:
> 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(-)
> 
[...]

> @@ -667,7 +670,7 @@ void cpumask_xor(struct cpumask *dstp, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_andnot - *dstp = *src1p & ~*src2p
> + * cpumask_andnot - *@dstp = *@src1p & ~*@src2p

The latter part needs to be "&~ *@src2p".

Note: kernel-doc (script) recognizes the pattern of *@name, but not ~*@name
at the moment.  (No warning from Sphinx, but the rendered doc doesn't look
right.)

>   * @dstp: the cpumask result
>   * @src1p: the first input
>   * @src2p: the second input
[...]

> @@ -729,7 +732,7 @@ bool cpumask_intersects(const struct cpumask *src1p, const struct cpumask *src2p
>  }
>  
>  /**
> - * cpumask_subset - (*src1p & ~*src2p) == 0
> + * cpumask_subset - (*@src1p & ~*@src2p) == 0

Ditto.

>   * @src1p: the first input
>   * @src2p: the second input
>   *
[...]

> @@ -789,11 +792,11 @@ unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumas
>  }
>  
>  /**
> - * cpumask_weight_andnot - Count of bits in (*srcp1 & ~*srcp2)
> + * cpumask_weight_andnot - Count of bits in (*@srcp1 & ~*@srcp2)

Ditto.

With above patterns taken care of:
Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

>   * @srcp1: the cpumask to count bits (< nr_cpu_ids) in.
>   * @srcp2: the cpumask to count bits (< nr_cpu_ids) in.
>   *
> - * Return: count of bits set in both *srcp1 and *srcp2
> + * Return: count of bits set in both *@srcp1 and *@srcp2
>   */
>  static __always_inline
>  unsigned int cpumask_weight_andnot(const struct cpumask *srcp1,
[...]

        Thanks, Akira

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

[Akira Yokosawa]

Hi again, 

Viresh Kumar wrote:
> 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(-)
> 

Didn't come up in your diff, but you need additional changes shown below:

diff --git a/include/linux/cpumask.h b/include/linux/cpumask.h
index 656d2208467e..a6c1961cc535 100644
--- a/include/linux/cpumask.h
+++ b/include/linux/cpumask.h
@@ -285,10 +285,10 @@ unsigned int cpumask_next_and(int n, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_next_and_wrap - get the next cpu in *src1p & *src2p, starting from
- *                        @n+1. If nothing found, wrap around and start from
+ * cpumask_next_and_wrap - get the next cpu in *@src1p & *@src2p, starting from
+ *                        @n+ 1. If nothing found, wrap around and start from
  *                        the beginning
- * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
+ * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
  * @src1p: the first cpumask pointer
  * @src2p: the second cpumask pointer
  *
@@ -306,9 +306,9 @@ unsigned int cpumask_next_and_wrap(int n, const struct cpumask *src1p,
 }
 
 /**
- * cpumask_next_wrap - get the next cpu in *src, starting from @n+1. If nothing
+ * cpumask_next_wrap - get the next cpu in *@src, starting from @n +1. If nothing
  *                    found, wrap around and start from the beginning
- * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
+ * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
  * @src: cpumask pointer
  *
  * Return: next set bit, wrapped if needed, or >= nr_cpu_ids if @src is empty.

Feel free to squash into your 1/2.
My R-b tag still stands.

        Thanks, Akira

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

[Viresh Kumar]

On 07-03-25, 19:57, Akira Yokosawa wrote:
> Didn't come up in your diff, but you need additional changes shown below:
> 
> diff --git a/include/linux/cpumask.h b/include/linux/cpumask.h
> index 656d2208467e..a6c1961cc535 100644
> --- a/include/linux/cpumask.h
> +++ b/include/linux/cpumask.h
> @@ -285,10 +285,10 @@ unsigned int cpumask_next_and(int n, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_next_and_wrap - get the next cpu in *src1p & *src2p, starting from
> - *                        @n+1. If nothing found, wrap around and start from
> + * cpumask_next_and_wrap - get the next cpu in *@src1p & *@src2p, starting from
> + *                        @n+ 1. If nothing found, wrap around and start from
>   *                        the beginning
> - * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
> + * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
>   * @src1p: the first cpumask pointer
>   * @src2p: the second cpumask pointer
>   *
> @@ -306,9 +306,9 @@ unsigned int cpumask_next_and_wrap(int n, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_next_wrap - get the next cpu in *src, starting from @n+1. If nothing
> + * cpumask_next_wrap - get the next cpu in *@src, starting from @n +1. If nothing
>   *                    found, wrap around and start from the beginning
> - * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
> + * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
>   * @src: cpumask pointer
>   *
>   * Return: next set bit, wrapped if needed, or >= nr_cpu_ids if @src is empty.

How did you find these ? I only looked for build warnings / errors earlier (with
make htmldocs). Anything else I should be doing to find these issues ?

Thanks for your help Akira.

-- 
viresh

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

[Akira Yokosawa]

Viresh Kumar wrote:
> On 07-03-25, 19:57, Akira Yokosawa wrote:
>> Didn't come up in your diff, but you need additional changes shown below:
>>
>> diff --git a/include/linux/cpumask.h b/include/linux/cpumask.h
>> index 656d2208467e..a6c1961cc535 100644
>> --- a/include/linux/cpumask.h
>> +++ b/include/linux/cpumask.h
>> @@ -285,10 +285,10 @@ unsigned int cpumask_next_and(int n, const struct cpumask *src1p,
>>  }
>>  
>>  /**
>> - * cpumask_next_and_wrap - get the next cpu in *src1p & *src2p, starting from
>> - *                        @n+1. If nothing found, wrap around and start from
>> + * cpumask_next_and_wrap - get the next cpu in *@src1p & *@src2p, starting from
>> + *                        @n+ 1. If nothing found, wrap around and start from
>>   *                        the beginning
>> - * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
>> + * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
>>   * @src1p: the first cpumask pointer
>>   * @src2p: the second cpumask pointer
>>   *
>> @@ -306,9 +306,9 @@ unsigned int cpumask_next_and_wrap(int n, const struct cpumask *src1p,
>>  }
>>  
>>  /**
>> - * cpumask_next_wrap - get the next cpu in *src, starting from @n+1. If nothing
>> + * cpumask_next_wrap - get the next cpu in *@src, starting from @n +1. If nothing
>>   *                    found, wrap around and start from the beginning
>> - * @n: the cpu prior to the place to search (i.e. search starts from @n+1)
>> + * @n: the cpu prior to the place to search (i.e. search starts from @n +1)
>>   * @src: cpumask pointer
>>   *
>>   * Return: next set bit, wrapped if needed, or >= nr_cpu_ids if @src is empty.
> 
> How did you find these ? I only looked for build warnings / errors earlier (with
> make htmldocs).   Anything else I should be doing to find these issues ?

Well, you need to see the rendered html pages in your browser. :-)

Or, look into the rst output from
   "scripts/kernel-doc -rst <file with kernel-doc comments>",
and see if it makes sense as reStructuredText.

It seems to me there are very few people actually do it ...

But I fat-fingered in the above diff.

>> @@ -285,10 +285,10 @@ unsigned int cpumask_next_and(int n, const struct cpumask *src1p,
>>  }
>>  
>>  /**
>> - * cpumask_next_and_wrap - get the next cpu in *src1p & *src2p, starting from
>> - *                        @n+1. If nothing found, wrap around and start from
>> + * cpumask_next_and_wrap - get the next cpu in *@src1p & *@src2p, starting from
>> + *                        @n+ 1. If nothing found, wrap around and start from
        Obviously, should be  @n +1.

>>   *                        the beginning

> 
> Thanks for your help Akira.
>

You are welcome.

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

[Yury Norov]

On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
> 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.
>   */
>  #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
>   * @srcp1: the first input
>   * @srcp2: the second input
>   *
> @@ -179,7 +179,7 @@ unsigned int cpumask_first_and(const struct cpumask *srcp1, const struct cpumask
>  }
>  
>  /**
> - * cpumask_first_and_and - return the first cpu from *srcp1 & *srcp2 & *srcp3
> + * cpumask_first_and_and - return the first cpu from *@srcp1 & *@srcp2 & *@srcp3
>   * @srcp1: the first input
>   * @srcp2: the second input
>   * @srcp3: the third input
> @@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);
>  #endif /* NR_CPUS */
>  
>  /**
> - * cpumask_next_and - get the next cpu in *src1p & *src2p
> + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
>   * @n: the cpu prior to the place to search (i.e. return will be > @n)
>   * @src1p: the first cpumask pointer
>   * @src2p: the second cpumask pointer

So the question: if some word in this particular comment block is
prefixed with @ symbol, can we teach kernel-doc to consider every
occurrence of this word as a variable?

Why I'm asking: before the "*src1p & *src2p" was a line of C code.
And because we are all C programmers here, it's really simple to ident
it and decode. After it looks like something weird, and I think many
of us will just mentally skip it.

I like kernel-docs and everything, but again, kernel sources should
stay readable, and particularly comments should stay human-readable.

> @@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>   * @mask1: the first cpumask pointer
>   * @mask2: the second cpumask pointer
>   *
> - * This saves a temporary CPU mask in many places.  It is equivalent to:
> + * This saves a temporary CPU mask in many places.  It is equivalent to::
> + *

I'm OK with extra line, but this double-colon. What for and what does
it mean?

>   *	struct cpumask tmp;
>   *	cpumask_and(&tmp, &mask1, &mask2);
>   *	for_each_cpu(cpu, &tmp)
> @@ -352,7 +353,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>   * @mask1: the first cpumask pointer
>   * @mask2: the second cpumask pointer
>   *
> - * This saves a temporary CPU mask in many places.  It is equivalent to:
> + * This saves a temporary CPU mask in many places.  It is equivalent to::
> + *
>   *	struct cpumask tmp;
>   *	cpumask_andnot(&tmp, &mask1, &mask2);
>   *	for_each_cpu(cpu, &tmp)
> @@ -369,7 +371,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>   * @mask1: the first cpumask pointer
>   * @mask2: the second cpumask pointer
>   *
> - * This saves a temporary CPU mask in many places.  It is equivalent to:
> + * This saves a temporary CPU mask in many places.  It is equivalent to::
> + *
>   *	struct cpumask tmp;
>   *	cpumask_or(&tmp, &mask1, &mask2);
>   *	for_each_cpu(cpu, &tmp)
> @@ -411,7 +414,7 @@ unsigned int cpumask_any_but(const struct cpumask *mask, unsigned int cpu)
>  }
>  
>  /**
> - * cpumask_any_and_but - pick an arbitrary cpu from *mask1 & *mask2, but not this one.
> + * cpumask_any_and_but - pick an arbitrary cpu from *@mask1 & *@mask2, but not this one.
>   * @mask1: the first input cpumask
>   * @mask2: the second input cpumask
>   * @cpu: the cpu to ignore
> @@ -545,7 +548,7 @@ static __always_inline void __cpumask_clear_cpu(int cpu, struct cpumask *dstp)
>   * cpumask_assign_cpu - assign a cpu in a cpumask
>   * @cpu: cpu number (< nr_cpu_ids)
>   * @dstp: the cpumask pointer
> - * @bool: the value to assign
> + * @value: the value to assign
>   */
>  static __always_inline void cpumask_assign_cpu(int cpu, struct cpumask *dstp, bool value)
>  {
> @@ -623,7 +626,7 @@ static __always_inline void cpumask_clear(struct cpumask *dstp)
>  }
>  
>  /**
> - * cpumask_and - *dstp = *src1p & *src2p
> + * cpumask_and - *@dstp = *@src1p & *@src2p
>   * @dstp: the cpumask result
>   * @src1p: the first input
>   * @src2p: the second input
> @@ -639,7 +642,7 @@ bool cpumask_and(struct cpumask *dstp, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_or - *dstp = *src1p | *src2p
> + * cpumask_or - *@dstp = *@src1p | *@src2p
>   * @dstp: the cpumask result
>   * @src1p: the first input
>   * @src2p: the second input
> @@ -653,7 +656,7 @@ void cpumask_or(struct cpumask *dstp, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_xor - *dstp = *src1p ^ *src2p
> + * cpumask_xor - *@dstp = *@src1p ^ *@src2p
>   * @dstp: the cpumask result
>   * @src1p: the first input
>   * @src2p: the second input
> @@ -667,7 +670,7 @@ void cpumask_xor(struct cpumask *dstp, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_andnot - *dstp = *src1p & ~*src2p
> + * cpumask_andnot - *@dstp = *@src1p & ~*@src2p
>   * @dstp: the cpumask result
>   * @src1p: the first input
>   * @src2p: the second input
> @@ -683,7 +686,7 @@ bool cpumask_andnot(struct cpumask *dstp, const struct cpumask *src1p,
>  }
>  
>  /**
> - * cpumask_equal - *src1p == *src2p
> + * cpumask_equal - *@src1p == *@src2p
>   * @src1p: the first input
>   * @src2p: the second input
>   *
> @@ -697,7 +700,7 @@ bool cpumask_equal(const struct cpumask *src1p, const struct cpumask *src2p)
>  }
>  
>  /**
> - * cpumask_or_equal - *src1p | *src2p == *src3p
> + * cpumask_or_equal - *@src1p | *@src2p == *@src3p
>   * @src1p: the first input
>   * @src2p: the second input
>   * @src3p: the third input
> @@ -714,7 +717,7 @@ bool cpumask_or_equal(const struct cpumask *src1p, const struct cpumask *src2p,
>  }
>  
>  /**
> - * cpumask_intersects - (*src1p & *src2p) != 0
> + * cpumask_intersects - (*@src1p & *@src2p) != 0
>   * @src1p: the first input
>   * @src2p: the second input
>   *
> @@ -729,7 +732,7 @@ bool cpumask_intersects(const struct cpumask *src1p, const struct cpumask *src2p
>  }
>  
>  /**
> - * cpumask_subset - (*src1p & ~*src2p) == 0
> + * cpumask_subset - (*@src1p & ~*@src2p) == 0
>   * @src1p: the first input
>   * @src2p: the second input
>   *
> @@ -743,7 +746,7 @@ bool cpumask_subset(const struct cpumask *src1p, const struct cpumask *src2p)
>  }
>  
>  /**
> - * cpumask_empty - *srcp == 0
> + * cpumask_empty - *@srcp == 0
>   * @srcp: the cpumask to that all cpus < nr_cpu_ids are clear.
>   *
>   * Return: true if srcp is empty (has no bits set), else false
> @@ -754,7 +757,7 @@ static __always_inline bool cpumask_empty(const struct cpumask *srcp)
>  }
>  
>  /**
> - * cpumask_full - *srcp == 0xFFFFFFFF...
> + * cpumask_full - *@srcp == 0xFFFFFFFF...
>   * @srcp: the cpumask to that all cpus < nr_cpu_ids are set.
>   *
>   * Return: true if srcp is full (has all bits set), else false
> @@ -765,10 +768,10 @@ static __always_inline bool cpumask_full(const struct cpumask *srcp)
>  }
>  
>  /**
> - * cpumask_weight - Count of bits in *srcp
> + * cpumask_weight - Count of bits in *@srcp
>   * @srcp: the cpumask to count bits (< nr_cpu_ids) in.

Here nr_cpu_ids is also a variable. Why you don't prefix it with @?

>   *
> - * Return: count of bits set in *srcp
> + * Return: count of bits set in *@srcp
>   */
>  static __always_inline unsigned int cpumask_weight(const struct cpumask *srcp)
>  {
> @@ -776,11 +779,11 @@ static __always_inline unsigned int cpumask_weight(const struct cpumask *srcp)
>  }
>  
>  /**
> - * cpumask_weight_and - Count of bits in (*srcp1 & *srcp2)
> + * cpumask_weight_and - Count of bits in (*@srcp1 & *@srcp2)
>   * @srcp1: the cpumask to count bits (< nr_cpu_ids) in.
>   * @srcp2: the cpumask to count bits (< nr_cpu_ids) in.
>   *
> - * Return: count of bits set in both *srcp1 and *srcp2
> + * Return: count of bits set in both *@srcp1 and *@srcp2
>   */
>  static __always_inline
>  unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumask *srcp2)
> @@ -789,11 +792,11 @@ unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumas
>  }
>  
>  /**
> - * cpumask_weight_andnot - Count of bits in (*srcp1 & ~*srcp2)
> + * cpumask_weight_andnot - Count of bits in (*@srcp1 & ~*@srcp2)
>   * @srcp1: the cpumask to count bits (< nr_cpu_ids) in.
>   * @srcp2: the cpumask to count bits (< nr_cpu_ids) in.
>   *
> - * Return: count of bits set in both *srcp1 and *srcp2
> + * Return: count of bits set in both *@srcp1 and *@srcp2
>   */
>  static __always_inline
>  unsigned int cpumask_weight_andnot(const struct cpumask *srcp1,
> @@ -803,7 +806,7 @@ unsigned int cpumask_weight_andnot(const struct cpumask *srcp1,
>  }
>  
>  /**
> - * cpumask_shift_right - *dstp = *srcp >> n
> + * cpumask_shift_right - *@dstp = *@srcp >> n
>   * @dstp: the cpumask result
>   * @srcp: the input to shift
>   * @n: the number of bits to shift by
> @@ -816,7 +819,7 @@ void cpumask_shift_right(struct cpumask *dstp, const struct cpumask *srcp, int n
>  }
>  
>  /**
> - * cpumask_shift_left - *dstp = *srcp << n
> + * cpumask_shift_left - *@dstp = *@srcp << n
>   * @dstp: the cpumask result
>   * @srcp: the input to shift
>   * @n: the number of bits to shift by
> @@ -829,7 +832,7 @@ void cpumask_shift_left(struct cpumask *dstp, const struct cpumask *srcp, int n)
>  }
>  
>  /**
> - * cpumask_copy - *dstp = *srcp
> + * cpumask_copy - *@dstp = *@srcp
>   * @dstp: the result
>   * @srcp: the input cpumask
>   */
> @@ -840,7 +843,7 @@ void cpumask_copy(struct cpumask *dstp, const struct cpumask *srcp)
>  }
>  
>  /**
> - * cpumask_any - pick an arbitrary cpu from *srcp
> + * cpumask_any - pick an arbitrary cpu from *@srcp
>   * @srcp: the input cpumask
>   *
>   * Return: >= nr_cpu_ids if no cpus set.
> @@ -848,7 +851,7 @@ void cpumask_copy(struct cpumask *dstp, const struct cpumask *srcp)
>  #define cpumask_any(srcp) cpumask_first(srcp)
>  
>  /**
> - * cpumask_any_and - pick an arbitrary cpu from *mask1 & *mask2
> + * cpumask_any_and - pick an arbitrary cpu from *@mask1 & *@mask2
>   * @mask1: the first input cpumask
>   * @mask2: the second input cpumask
>   *
> @@ -941,7 +944,7 @@ bool zalloc_cpumask_var_node(cpumask_var_t *mask, gfp_t flags, int node)
>  /**
>   * alloc_cpumask_var - allocate a struct cpumask
>   * @mask: pointer to cpumask_var_t where the cpumask is returned
> - * @flags: GFP_ flags
> + * @flags: %GFP_ flags
>   *
>   * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
>   * a nop returning a constant 1 (in <linux/cpumask.h>).
> -- 
> 2.31.1.272.g89b43f80a514

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

[Viresh Kumar]

On 07-03-25, 12:05, Yury Norov wrote:
> On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
> >  /**
> > - * cpumask_next_and - get the next cpu in *src1p & *src2p
> > + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
> >   * @n: the cpu prior to the place to search (i.e. return will be > @n)
> >   * @src1p: the first cpumask pointer
> >   * @src2p: the second cpumask pointer
> 
> So the question: if some word in this particular comment block is
> prefixed with @ symbol, can we teach kernel-doc to consider every
> occurrence of this word as a variable?
> 
> Why I'm asking: before the "*src1p & *src2p" was a line of C code.
> And because we are all C programmers here, it's really simple to ident
> it and decode. After it looks like something weird, and I think many
> of us will just mentally skip it.
> 
> I like kernel-docs and everything, but again, kernel sources should
> stay readable, and particularly comments should stay human-readable.

Jonathan / Akira, can you please answer this one ?

> > @@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
> >   * @mask1: the first cpumask pointer
> >   * @mask2: the second cpumask pointer
> >   *
> > - * This saves a temporary CPU mask in many places.  It is equivalent to:
> > + * This saves a temporary CPU mask in many places.  It is equivalent to::
> > + *
> 
> I'm OK with extra line, but this double-colon. What for and what does
> it mean?

Without this we get: "ERROR: Unexpected indentation", for the last
line of the code block that contains: "        ...".

The double-colon creates a code-block for the below code and gets rid
of the warning.
> 
> >  /**
> > - * cpumask_weight - Count of bits in *srcp
> > + * cpumask_weight - Count of bits in *@srcp
> >   * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
> 
> Here nr_cpu_ids is also a variable. Why you don't prefix it with @?

I was only looking to fix the build warnings / errors for now, and did
not look into detail for such issues. Yes, it should be marked with @.
I will try to go through all the comments now and fix such issues.

-- 
viresh

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

[Viresh Kumar]

On 10-03-25, 11:45, Viresh Kumar wrote:
> On 07-03-25, 12:05, Yury Norov wrote:
> > >  /**
> > > - * cpumask_weight - Count of bits in *srcp
> > > + * cpumask_weight - Count of bits in *@srcp
> > >   * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
> > 
> > Here nr_cpu_ids is also a variable. Why you don't prefix it with @?

Hmm, I thought @ is applied only to function arguments. Not sure what
should be done with nr_cpu_ids.

Akira ?

-- 
viresh

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

[Akira Yokosawa]

Hi,

Viresh Kumar wrote:
> On 10-03-25, 11:45, Viresh Kumar wrote:
>> On 07-03-25, 12:05, Yury Norov wrote:
>>>>  /**
>>>> - * cpumask_weight - Count of bits in *srcp
>>>> + * cpumask_weight - Count of bits in *@srcp
>>>>   * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
>>>
>>> Here nr_cpu_ids is also a variable. Why you don't prefix it with @?
> 
> Hmm, I thought @ is applied only to function arguments. Not sure what
> should be done with nr_cpu_ids.
> 
> Akira ?

Section "Highlights and cross-references" in
Documentation/doc-guide/kernel-doc.sty says:

    ``@parameter``
    Name of a function parameter. (No cross-referencing, just formatting.)

It's just formatting.  Putting "@" to a non argument name won't result
in any warning.  (At least current kernel-doc goes.)

kernel-doc is just our own convention, which can change any moment,
hopefully in backward compatible manner.

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

[Akira Yokosawa]

Hi,

Viresh Kumar wrote:
> On 07-03-25, 12:05, Yury Norov wrote:
>> On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
>>>  /**
>>> - * cpumask_next_and - get the next cpu in *src1p & *src2p
>>> + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
>>>   * @n: the cpu prior to the place to search (i.e. return will be > @n)
>>>   * @src1p: the first cpumask pointer
>>>   * @src2p: the second cpumask pointer
>>
>> So the question: if some word in this particular comment block is
>> prefixed with @ symbol, can we teach kernel-doc to consider every
>> occurrence of this word as a variable?

That is not impossible, I would say.

>>
>> Why I'm asking: before the "*src1p & *src2p" was a line of C code.
>> And because we are all C programmers here, it's really simple to ident
>> it and decode. After it looks like something weird, and I think many
>> of us will just mentally skip it.
>>
>> I like kernel-docs and everything, but again, kernel sources should
>> stay readable, and particularly comments should stay human-readable.
> 
> Jonathan / Akira, can you please answer this one ?

I was not around when transition to Sphinx was made in 2016, and I don't
know much of kernel-doc (or its predecessor doc-book) comment format.

So below is my wild guesses.

Current Documentation/doc-guide/kernel-doc.rst has no mention of "*" WRT
where it is allowed or disallowed, which results in occasional complaints
from Sphinx on unmatched start/end of emphasis.

However, the use of "*" is indicated for itemized list, which directly
employs reST format.

It doesn't say anything about literal/code blocks, either.

So I have to say that current kernel-doc has quite a few of undefined
things on reST output.

kernel-doc in python3 might help untangle the mess.

This all need some consensus on kenrel-doc behavior to be reached, and
update/enhance of kernel-doc (script).

So my suggestion would be to hold these changes for the time being.

> 
>>> @@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>>>   * @mask1: the first cpumask pointer
>>>   * @mask2: the second cpumask pointer
>>>   *
>>> - * This saves a temporary CPU mask in many places.  It is equivalent to:
>>> + * This saves a temporary CPU mask in many places.  It is equivalent to::
>>> + *
>>
>> I'm OK with extra line, but this double-colon. What for and what does
>> it mean?
> 
> Without this we get: "ERROR: Unexpected indentation", for the last
> line of the code block that contains: "        ...".
> 
> The double-colon creates a code-block for the below code and gets rid
> of the warning.
>>
>>>  /**
>>> - * cpumask_weight - Count of bits in *srcp
>>> + * cpumask_weight - Count of bits in *@srcp
>>>   * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
>>
>> Here nr_cpu_ids is also a variable. Why you don't prefix it with @?
> 
> I was only looking to fix the build warnings / errors for now, and did
> not look into detail for such issues. Yes, it should be marked with @.
> I will try to go through all the comments now and fix such issues.
>

Provided the brokenness of kernel-doc spec & script, I think you can
wait until it is properly fixed/enhanced.

The problem is: Is there somebody who would be interested enough to do
such an improvement?

        Thanks, Akira

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

[Jonathan Corbet]

Yury Norov <yury.norov@gmail.com> writes:

> On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
>>  /**
>> - * cpumask_first_and_and - return the first cpu from *srcp1 & *srcp2 & *srcp3
>> + * cpumask_first_and_and - return the first cpu from *@srcp1 & *@srcp2 & *@srcp3
>>   * @srcp1: the first input
>>   * @srcp2: the second input
>>   * @srcp3: the third input
>> @@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);
>>  #endif /* NR_CPUS */
>>  
>>  /**
>> - * cpumask_next_and - get the next cpu in *src1p & *src2p
>> + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
>>   * @n: the cpu prior to the place to search (i.e. return will be > @n)
>>   * @src1p: the first cpumask pointer
>>   * @src2p: the second cpumask pointer
>
> So the question: if some word in this particular comment block is
> prefixed with @ symbol, can we teach kernel-doc to consider every
> occurrence of this word as a variable?
>
> Why I'm asking: before the "*src1p & *src2p" was a line of C code.
> And because we are all C programmers here, it's really simple to ident
> it and decode. After it looks like something weird, and I think many
> of us will just mentally skip it.
>
> I like kernel-docs and everything, but again, kernel sources should
> stay readable, and particularly comments should stay human-readable.

I'm sure it *can* be done, yes.  In truth, given that we're dealing with
named parameters in a prototype that we are decoding, we might be able,
with enough clever programming, to do away with that markup entirely.

It's just a matter of programming :)

I've added Mauro, since he's in the process of replacing kernel-doc
entirely.  I suspect he has enough on his hands at the moment without
adding extra objectives, and will want to get that replacement
successfully done first.  But it's a worthy goal to keep in mind.


>> @@ -334,7 +334,8 @@ unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta
>>   * @mask1: the first cpumask pointer
>>   * @mask2: the second cpumask pointer
>>   *
>> - * This saves a temporary CPU mask in many places.  It is equivalent to:
>> + * This saves a temporary CPU mask in many places.  It is equivalent to::
>> + *
>
> I'm OK with extra line, but this double-colon. What for and what does
> it mean?

The :: introduces a literal block, which needs a blank line to start it.

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Mon, 10 Mar 2025 08:07:06 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Yury Norov <yury.norov@gmail.com> writes:
> 
> > On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:  
> >>  /**
> >> - * cpumask_first_and_and - return the first cpu from *srcp1 & *srcp2 & *srcp3
> >> + * cpumask_first_and_and - return the first cpu from *@srcp1 & *@srcp2 & *@srcp3
> >>   * @srcp1: the first input
> >>   * @srcp2: the second input
> >>   * @srcp3: the third input
> >> @@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);
> >>  #endif /* NR_CPUS */
> >>  
> >>  /**
> >> - * cpumask_next_and - get the next cpu in *src1p & *src2p
> >> + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
> >>   * @n: the cpu prior to the place to search (i.e. return will be > @n)
> >>   * @src1p: the first cpumask pointer
> >>   * @src2p: the second cpumask pointer  

IMO, the better would be to use:

	cpumask_next_and - get the next cpu in @src1p and @src2p

e. g. I would avoid the asterisk and the "&" symbol at the comment - the
less symbols we have there, the better for people reading the C code.

> > So the question: if some word in this particular comment block is
> > prefixed with @ symbol, can we teach kernel-doc to consider every
> > occurrence of this word as a variable?
> >
> > Why I'm asking: before the "*src1p & *src2p" was a line of C code.
> > And because we are all C programmers here, it's really simple to ident
> > it and decode. After it looks like something weird, and I think many
> > of us will just mentally skip it.
> >
> > I like kernel-docs and everything, but again, kernel sources should
> > stay readable, and particularly comments should stay human-readable.  
> 
> I'm sure it *can* be done, yes.  In truth, given that we're dealing with
> named parameters in a prototype that we are decoding, we might be able,
> with enough clever programming, to do away with that markup entirely.

Please notice that, if we use:

	/**
	 * cpumask_first_and - return the first cpu from *srcp1 & @srcp2
	 */

The ReST output from kernel-doc is:

	.. c:function:: unsigned int cpumask_first_and (const struct cpumask *srcp1, const struct cpumask *srcp2)

	   return the first cpu from *srcp1 & **srcp2**

Placing an asterisk before "@" won't work, as, in order to produce a 
valid ReST syntax, the output for srcp2 would need to be be: 

	**\*srcp2**

Please notice that I didn't test if the above would work on Sphinx. 
I remember we had some issues with things similar to that in the past,
with older versions of the toolchain. So, we need first to test it
against minimal and current versions of toolchain to be sure that this
would work.

Assuming that the above works, we'll need to define how this
will be represented at the source code. IMO, neither @*var nor *@var
would be great. Perhaps we could stick with *var, but then we would
need to ensure that this won't cause any regressions with already
existing kernel-doc macros.

Thanks,
Mauro

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

[Viresh Kumar]

Hi Yury / Akira / Mauro,

On 07-03-25, 12:05, Yury Norov wrote:
> On Fri, Mar 07, 2025 at 01:04:51PM +0530, Viresh Kumar wrote:
> >  /**
> > - * cpumask_next_and - get the next cpu in *src1p & *src2p
> > + * cpumask_next_and - get the next cpu in *@src1p & *@src2p
> >   * @n: the cpu prior to the place to search (i.e. return will be > @n)
> >   * @src1p: the first cpumask pointer
> >   * @src2p: the second cpumask pointer
> 
> So the question: if some word in this particular comment block is
> prefixed with @ symbol, can we teach kernel-doc to consider every
> occurrence of this word as a variable?
> 
> Why I'm asking: before the "*src1p & *src2p" was a line of C code.
> And because we are all C programmers here, it's really simple to ident
> it and decode. After it looks like something weird, and I think many
> of us will just mentally skip it.
> 
> I like kernel-docs and everything, but again, kernel sources should
> stay readable, and particularly comments should stay human-readable.

I was looking to get a public links to cpumask APIs, like:

https://docs.kernel.org/core-api/kernel-api.html#bitmap-operations

which I can use from the (WIP) Rust cpumask documentation.

Can you suggest how do I move ahead with this ?

- Let the warnings be there and keep the comment as "... cpu in *src1p & *stc2p" ?

- Something like what Mauro suggested: "... cpu in @src1p and @stc2p" ? 

- Something else ?

-- 
viresh

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

[Mauro Carvalho Chehab]

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

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

[Akira Yokosawa]

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

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

[Mauro Carvalho Chehab]

Em Tue, 11 Mar 2025 00:27:47 +0900
Akira Yokosawa <akiyks@gmail.com> 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
> 

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

[Viresh Kumar]

On 10-03-25, 15:53, Mauro Carvalho Chehab wrote:
> >  /**
> > - * 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.

I see. I was only looking at the html output earlier and that was
showing up correctly.

   return the first cpu from *srcp1 & *srcp2


Tried with "scripts/kernel-doc -rst" now and it does show

   return the first cpu from ***srcp1** & ***srcp2**

-- 
viresh

[PATCH V2 2/2] docs: core-api: Update kernel-api.rst to include cpumask.h

[Viresh Kumar]

Updated Documentation/core-api/kernel-api.rst to include `cpumask.h`,
providing better reference for CPU mask operations in the kernel API.

Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
---
 Documentation/core-api/kernel-api.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index ae92a2571388..5817632381f9 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -90,6 +90,12 @@ Bitmap Operations
 .. kernel-doc:: include/linux/bitmap.h
    :internal:
 
+Cpumask Operations
+------------------
+
+.. kernel-doc:: include/linux/cpumask.h
+   :internal:
+
 Command-line Parsing
 --------------------
 
-- 
2.31.1.272.g89b43f80a514