Skip to contentSkip to conversation

rculist: Describe variadic macro argument in a Sphinx-compatible way

PATCH In review Jonathan Neuschäfer 3 participants 7 messages Oct 4, 2019 – Oct 6, 2019 RCU

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 rculist: Describe variadic macro argument in a Sphinx-compatible way

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

---
 include/linux/rculist.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/rculist.h +2 -2
index 4158b7212936..61c6728a71f7 100644
@@ -361,7 +361,7 @@ static inline void list_splice_tail_init_rcu(struct list_head *list,
  * @pos:	the type * to use as a loop cursor.
  * @head:	the head for your list.
  * @member:	the name of the list_head within the struct.
- * @cond:	optional lockdep expression if called from non-RCU protection.
+ * @cond...:	optional lockdep expression if called from non-RCU protection.
  *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as list_add_rcu()
@@ -636,7 +636,7 @@ static inline void hlist_add_behind_rcu(struct hlist_node *n,
  * @pos:	the type * to use as a loop cursor.
  * @head:	the head for your list.
  * @member:	the name of the hlist_node within the struct.
- * @cond:	optional lockdep expression if called from non-RCU protection.
+ * @cond...:	optional lockdep expression if called from non-RCU protection.
  *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as hlist_add_head_rcu()

--
2.20.1

maintainer
#1 lore raw
Quoted 8 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Applied for testing and review, thank you!

Joel, does this look sane to you?

Thanx, Paul

Quoted 29 lines
---
 include/linux/rculist.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/rculist.h +2 -3
index 4158b7212936..61c6728a71f7 100644
@@ -361,7 +361,7 @@ static inline void list_splice_tail_init_rcu(struct list_head *list,
  * @pos:	the type * to use as a loop cursor.
  * @head:	the head for your list.
  * @member:	the name of the list_head within the struct.
- * @cond:	optional lockdep expression if called from non-RCU protection.
+ * @cond...:	optional lockdep expression if called from non-RCU protection.
  *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as list_add_rcu()
@@ -636,7 +636,7 @@ static inline void hlist_add_behind_rcu(struct hlist_node *n,
  * @pos:	the type * to use as a loop cursor.
  * @head:	the head for your list.
  * @member:	the name of the hlist_node within the struct.
- * @cond:	optional lockdep expression if called from non-RCU protection.
+ * @cond...:	optional lockdep expression if called from non-RCU protection.
  *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as hlist_add_head_rcu()
--

2.20.1

#2 lore raw
Quoted 7 lines · Paul E. McKenney
Quoted 6 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Hmm, small detail that I didn't realize before: It's actually the kernel-doc script, not Sphinx, that can't deal with variadic macro arguments and thus requires this patch.

So it may also be possible to fix the script instead. (I have not looked into how much work that would be.)

Thanks,
Jonathan Neuschäfer

maintainer
#3 lore raw
Quoted 9 lines · Jonathan Neuschäfer
Quoted 7 lines · Paul E. McKenney
Quoted 6 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Quoted 6 lines

Hmm, small detail that I didn't realize before: It's actually the kernel-doc script, not Sphinx, that can't deal with variadic macro arguments and thus requires this patch.

So it may also be possible to fix the script instead. (I have not looked into how much work that would be.)

OK, thank you for letting me know. I will keep your patch for the moment, but please let me know if the fix can be elsewhere.

Thanx, Paul

#4 lore raw
Quoted 14 lines · Paul E. McKenney
Quoted 13 lines · Jonathan Neuschäfer
Quoted 7 lines · Paul E. McKenney
Quoted 6 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Hmm, small detail that I didn't realize before: It's actually the kernel-doc script, not Sphinx, that can't deal with variadic macro arguments and thus requires this patch.

Quoted 7 lines
Quoted 2 lines

So it may also be possible to fix the script instead. (I have not looked into how much work that would be.)

OK, thank you for letting me know. I will keep your patch for the moment, but please let me know if the fix can be elsewhere.

Thanx, Paul

Turns out the actual fix in scripts/kernel-doc is easy enough:

scripts/kernel-doc +4 -0
@@ -1449,6 +1449,10 @@ sub push_parameter($$$$) {
 	      # handles unnamed variable parameters
 	      $param = "...";
 	    }
+	    elsif ($param =~ /\w\.\.\.$/) {
+	      # for named variable parameters of the form `x...`, remove the dots
+	      $param =~ s/\.\.\.$//;
+	    }
 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
 		$parameterdescs{$param} = "variable arguments";
 	    }

... but there are other macros in the code base that are documented using the 'x...' syntax, so I guess it's best to take my initial patch (or something similar) now, and I'll fix kernel-doc later, in a longer patchset that also cleans up the fallout.

Thanks,
Jonathan Neuschäfer

maintainer
#5 lore raw
Quoted 39 lines · Jonathan Neuschäfer
Quoted 14 lines · Paul E. McKenney
Quoted 13 lines · Jonathan Neuschäfer
Quoted 7 lines · Paul E. McKenney
Quoted 6 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Hmm, small detail that I didn't realize before: It's actually the kernel-doc script, not Sphinx, that can't deal with variadic macro arguments and thus requires this patch.

Quoted 7 lines
Quoted 2 lines

So it may also be possible to fix the script instead. (I have not looked into how much work that would be.)

OK, thank you for letting me know. I will keep your patch for the moment, but please let me know if the fix can be elsewhere.

Thanx, Paul

Turns out the actual fix in scripts/kernel-doc is easy enough:

scripts/kernel-doc +4 -0
@@ -1449,6 +1449,10 @@ sub push_parameter($$$$) {
 	      # handles unnamed variable parameters
 	      $param = "...";
 	    }
+	    elsif ($param =~ /\w\.\.\.$/) {
+	      # for named variable parameters of the form `x...`, remove the dots
+	      $param =~ s/\.\.\.$//;
+	    }
 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
 		$parameterdescs{$param} = "variable arguments";
 	    }
Quoted 4 lines

... but there are other macros in the code base that are documented using the 'x...' syntax, so I guess it's best to take my initial patch (or something similar) now, and I'll fix kernel-doc later, in a longer patchset that also cleans up the fallout.

You got it! ;-)

Thanx, Paul

#6 lore raw
In reply to Paul E. McKenney
Quoted 5 lines · Paul E. McKenney
Quoted 4 lines · Jonathan Neuschäfer

Without this patch, Sphinx shows "variable arguments" as the description of the cond argument, rather than the intended description, and prints the following warnings:

Quoted 8 lines
Quoted 4 lines

./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

Applied for testing and review, thank you!

Joel, does this look sane to you?

Sorry for late reply due to weekend. Yes, looks good to me.

thanks,

- Joel