docs: core-api: Update kernel-api.rst to include cpumask.h
Subsystems (2)
v2 cover docs: core-api: Update kernel-api.rst to include cpumask.h
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(-)
Signature · 1 line
2.31.1.272.g89b43f80a514
PATCH v2 1/2 cpumask: Fix kernel-doc formatting errors in cpumask.h
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".
--- include/linux/cpumask.h | 65 +++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 31 deletions(-)
include/linux/cpumask.h +34 -31
@@ -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>).
Signature · 1 line
2.31.1.272.g89b43f80a514
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
Hi,
Only a couple of minor nits.
Quoted 11 lines · 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 <[email protected]>--- include/linux/cpumask.h | 65 +++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 31 deletions(-)
[...]
include/linux/cpumask.h void cpumask_xor(struct cpumask *dstp, const struct cpumask *src1p, · line 673
Quoted 6 lines
include/linux/cpumask.h +1
-1@@ -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.)
Quoted 3 lines
include/linux/cpumask.h +0
-0* @dstp: the cpumask result * @src1p: the first input * @src2p: the second input
[...]
include/linux/cpumask.h bool cpumask_intersects(const struct cpumask *src1p, const struct cpumask *src2p · line 735
Quoted 6 lines
include/linux/cpumask.h +1
-1@@ -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.
Quoted 3 lines
include/linux/cpumask.h +0
-0* @src1p: the first input * @src2p: the second input *
[...]
include/linux/cpumask.h unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumas · line 795
Quoted 6 lines
include/linux/cpumask.h +1
-1@@ -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:
include/linux/cpumask.h unsigned int cpumask_weight_and(const struct cpumask *srcp1, const struct cpumas · line 802
Quoted 8 lines
include/linux/cpumask.h +1
-1* @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
In reply to Viresh KumarHi again,
Quoted 11 lines · 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 <[email protected]>--- 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:
include/linux/cpumask.h +5 -5
@@ -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
Quoted 22 lines · Akira Yokosawa
Didn't come up in your diff, but you need additional changes shown below:
include/linux/cpumask.h +3
-3@@ -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, }
include/linux/cpumask.h unsigned int cpumask_next_and_wrap(int n, const struct cpumask *src1p, · line 314
Quoted 10 lines
include/linux/cpumask.h +2
-2/** -* 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.
Signature · 1 line
viresh
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
Quoted 24 lines · Viresh Kumar
Quoted 23 lines · Akira Yokosawa
Didn't come up in your diff, but you need additional changes shown below:
include/linux/cpumask.h +3
-3@@ -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, }
Quoted 12 lines
include/linux/cpumask.h unsigned int cpumask_next_and_wrap(int n, const struct cpumask *src1p, · line 314
Quoted 9 lines
include/linux/cpumask.h +2
-2/** -* 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.
Quoted 8 lines
include/linux/cpumask.h unsigned int cpumask_next_and(int n, const struct cpumask *src1p, · line 289
Quoted 8 lines
include/linux/cpumask.h +2
-2@@ -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.
Quoted 5 lines
include/linux/cpumask.h unsigned int cpumask_next_and(int n, const struct cpumask *src1p, · line 290
Quoted 1 line
include/linux/cpumask.h +0
-0* the beginning Thanks for your help Akira.
You are welcome.
Yury Norov
maintainerRe: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
In reply to Viresh KumarQuoted 43 lines · 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 <[email protected]>--- include/linux/cpumask.h | 65 +++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 31 deletions(-)include/linux/cpumask.h +3
-3@@ -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
include/linux/cpumask.h unsigned int cpumask_any_distribute(const struct cpumask *srcp); · line 272
Quoted 8 lines
include/linux/cpumask.h +1
-1@@ -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.
include/linux/cpumask.h unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta · line 338
Quoted 7 lines
include/linux/cpumask.h +2
-1@@ -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?
Quoted 132 lines
include/linux/cpumask.h +16
-14* 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
include/linux/cpumask.h static __always_inline bool cpumask_full(const struct cpumask *srcp) · line 772
Quoted 6 lines
include/linux/cpumask.h +1
-1@@ -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 @?
Quoted 90 lines
include/linux/cpumask.h +11
-11* -* 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>). Signature · 1 line
2.31.1.272.g89b43f80a514
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
Quoted 12 lines · Yury Norov
Quoted 6 lines · Viresh Kumar
/**
- *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 pointerSo 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?
Quoted 7 lines
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 ?
Quoted 10 lines
include/linux/cpumask.h unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta · line 338
Quoted 7 lines
include/linux/cpumask.h +2
-1@@ -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.
Quoted 7 lines
include/linux/cpumask.h static __always_inline bool cpumask_full(const struct cpumask *srcp) · line 772
Quoted 5 lines
include/linux/cpumask.h +1
-1/** -* 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_idsis 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.
Signature · 1 line
viresh
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
Quoted 7 lines · Viresh Kumar
Quoted 6 lines · Yury Norov
Quoted 4 lines
/**
- *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_idsis 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 ?
Signature · 1 line
viresh
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
Hi,
Quoted 7 lines · Viresh Kumar
Quoted 6 lines · Viresh Kumar
Quoted 5 lines · Yury Norov
Quoted 4 lines
/**
- *cpumask_weight- Count of bits in *srcp
+ *cpumask_weight- Count of bits in *@srcp
* @srcp: the cpumask to count bits (<nr_cpu_ids) in.
Quoted 6 lines
Quoted 1 line
Quoted 1 line
Here
nr_cpu_idsis 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" inDocumentation/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
In reply to Viresh KumarHi,
Quoted 9 lines · Viresh Kumar
Quoted 8 lines · Yury Norov
Quoted 6 lines · Viresh Kumar
/**
- *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
Quoted 3 lines
Quoted 3 lines
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.
Quoted 10 lines
Quoted 8 lines
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.
Quoted 23 lines
Quoted 11 lines
include/linux/cpumask.h unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta · line 338
Quoted 8 lines
include/linux/cpumask.h +2
-1@@ -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.
Quoted 6 lines
Quoted 5 lines
include/linux/cpumask.h +1
-1/** -* cpumask_weight - Count of bits in *srcp +* cpumask_weight - Count of bits in *@srcp * @srcp: the cpumask to count bits (< nr_cpu_ids) in.
Quoted 6 lines
Quoted 1 line
Here
nr_cpu_idsis 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
Jonathan Corbet
maintainerRe: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
In reply to Yury NorovQuoted 21 lines · Yury Norov
Quoted 7 lines · Viresh Kumar
/**
- *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 inputinclude/linux/cpumask.h unsigned int cpumask_any_distribute(const struct cpumask *srcp); · line 272
Quoted 8 lines
include/linux/cpumask.h +1
-1@@ -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?
Quoted 7 lines
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.
Quoted 10 lines
include/linux/cpumask.h unsigned int __pure cpumask_next_wrap(int n, const struct cpumask *mask, int sta · line 338
Quoted 7 lines
include/linux/cpumask.h +2
-1@@ -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
Em Mon, 10 Mar 2025 08:07:06 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 12 lines
Quoted 10 lines · Yury Norov
Quoted 9 lines · Viresh Kumar
/**
- *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 inputinclude/linux/cpumask.h +0
-0@@ -266,7 +266,7 @@ unsigned int cpumask_any_distribute(const struct cpumask *srcp);#endif /* NR_CPUS */
Quoted 6 lines
Quoted 6 lines
include/linux/cpumask.h unsigned int cpumask_any_distribute(const struct cpumask *srcp); · line 272
Quoted 6 lines
include/linux/cpumask.h +1
-1/** -* 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.
Quoted 9 lines
Quoted 9 lines
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.
Quoted 6 lines
Quoted 2 lines
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
In reply to Yury NorovHi Yury / Akira / Mauro,
Quoted 12 lines · Yury Norov
Quoted 6 lines · Viresh Kumar
/**
- *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 pointerSo 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?
Quoted 7 lines
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 ?
Signature · 1 line
viresh
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
In reply to Viresh KumarEm Fri, 7 Mar 2025 13:04:51 +0530
Viresh Kumar <[email protected]> escreveu:
Quoted 16 lines
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 <[email protected]>--- include/linux/cpumask.h | 65 +++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 31 deletions(-)include/linux/cpumask.h +0
-0
include/linux/cpumask.h line 23
Quoted 5 lines
include/linux/cpumask.h +1
-1@@ -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.
include/linux/cpumask.h static __always_inline unsigned int cpumask_first_zero(const struct cpumask *src · line 169
Quoted 9 lines
include/linux/cpumask.h +1
-1*/ #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
Hi,
Quoted 1 line · Mauro Carvalho Chehab
Em Fri, 7 Mar 2025 13:04:51 +0530
[...]
Quoted 18 lines
Quoted 3 lines
/**
- *cpumask_first_and- return the first cpu from *srcp1 & *srcp2
+ *cpumask_first_and- return the first cpu from *@srcp1 & *@srcp2I 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 & *@srp3The 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.:
Quoted 7 lines
- 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
Em Tue, 11 Mar 2025 00:27:47 +0900
Akira Yokosawa <[email protected]> escreveu:
Quoted 35 lines
Hi,
Quoted 1 line · Mauro Carvalho Chehab
Em Fri, 7 Mar 2025 13:04:51 +0530
[...]
Quoted 18 lines
Quoted 3 lines
/**
- *cpumask_first_and- return the first cpu from *srcp1 & *srcp2
+ *cpumask_first_and- return the first cpu from *@srcp1 & *@srcp2I 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 & *@srp3The 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.:
Quoted 7 lines
- 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.
Quoted 6 lines
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.
Quoted 3 lines
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.
Quoted 3 lines
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.
Quoted 3 lines
Thanks, Akira
Re: [PATCH V2 1/2] cpumask: Fix kernel-doc formatting errors in cpumask.h
In reply to Mauro Carvalho ChehabQuoted 5 lines · Mauro Carvalho Chehab
Quoted 3 lines
/**
- *cpumask_first_and- return the first cpu from *srcp1 & *srcp2
+ *cpumask_first_and- return the first cpu from *@srcp1 & *@srcp2I 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**
Signature · 1 line
viresh
PATCH v2 2/2 docs: core-api: Update kernel-api.rst to include cpumask.h
In reply to Viresh KumarUpdated Documentation/core-api/kernel-api.rst to include cpumask.h, providing better reference for CPU mask operations in the kernel API.
--- Documentation/core-api/kernel-api.rst | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/core-api/kernel-api.rst +6 -0
@@ -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 --------------------
Signature · 1 line
2.31.1.272.g89b43f80a514