RCU Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
@ 2019-10-04 21:54 Jonathan Neuschäfer
  2019-10-04 22:24 ` Paul E. McKenney
  0 siblings, 1 reply; 7+ messages in thread
From: Jonathan Neuschäfer @ 2019-10-04 21:54 UTC (permalink / raw)
  To: rcu
  Cc: Jonathan Neuschäfer, Paul E. McKenney, Josh Triplett,
	Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes,
	linux-kernel

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'

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
---
 include/linux/rculist.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/rculist.h b/include/linux/rculist.h
index 4158b7212936..61c6728a71f7 100644
--- a/include/linux/rculist.h
+++ b/include/linux/rculist.h
@@ -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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-04 21:54 [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way Jonathan Neuschäfer
@ 2019-10-04 22:24 ` Paul E. McKenney
  2019-10-04 23:23   ` Jonathan Neuschäfer
  2019-10-06 23:44   ` Joel Fernandes
  0 siblings, 2 replies; 7+ messages in thread
From: Paul E. McKenney @ 2019-10-04 22:24 UTC (permalink / raw)
  To: Jonathan Neuschäfer
  Cc: rcu, Josh Triplett, Steven Rostedt, Mathieu Desnoyers,
	Lai Jiangshan, Joel Fernandes, linux-kernel

On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> 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'
> 
> Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>

Applied for testing and review, thank you!

Joel, does this look sane to you?

							Thanx, Paul

> ---
>  include/linux/rculist.h | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/include/linux/rculist.h b/include/linux/rculist.h
> index 4158b7212936..61c6728a71f7 100644
> --- a/include/linux/rculist.h
> +++ b/include/linux/rculist.h
> @@ -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
> 

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-04 22:24 ` Paul E. McKenney
@ 2019-10-04 23:23   ` Jonathan Neuschäfer
  2019-10-05 13:33     ` Paul E. McKenney
  2019-10-06 23:44   ` Joel Fernandes
  1 sibling, 1 reply; 7+ messages in thread
From: Jonathan Neuschäfer @ 2019-10-04 23:23 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Jonathan Neuschäfer, rcu, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 893 bytes --]

On Fri, Oct 04, 2019 at 03:24:39PM -0700, Paul E. McKenney wrote:
> On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> > 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-04 23:23   ` Jonathan Neuschäfer
@ 2019-10-05 13:33     ` Paul E. McKenney
  2019-10-05 19:31       ` Jonathan Neuschäfer
  0 siblings, 1 reply; 7+ messages in thread
From: Paul E. McKenney @ 2019-10-05 13:33 UTC (permalink / raw)
  To: Jonathan Neuschäfer
  Cc: rcu, Josh Triplett, Steven Rostedt, Mathieu Desnoyers,
	Lai Jiangshan, Joel Fernandes, linux-kernel

On Sat, Oct 05, 2019 at 01:23:28AM +0200, Jonathan Neuschäfer wrote:
> On Fri, Oct 04, 2019 at 03:24:39PM -0700, Paul E. McKenney wrote:
> > On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> > > 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.)

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

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-05 13:33     ` Paul E. McKenney
@ 2019-10-05 19:31       ` Jonathan Neuschäfer
  2019-10-05 19:35         ` Paul E. McKenney
  0 siblings, 1 reply; 7+ messages in thread
From: Jonathan Neuschäfer @ 2019-10-05 19:31 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Jonathan Neuschäfer, rcu, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 2064 bytes --]

On Sat, Oct 05, 2019 at 06:33:30AM -0700, Paul E. McKenney wrote:
> On Sat, Oct 05, 2019 at 01:23:28AM +0200, Jonathan Neuschäfer wrote:
> > On Fri, Oct 04, 2019 at 03:24:39PM -0700, Paul E. McKenney wrote:
> > > On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> > > > 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.)
> 
> 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:

--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-05 19:31       ` Jonathan Neuschäfer
@ 2019-10-05 19:35         ` Paul E. McKenney
  0 siblings, 0 replies; 7+ messages in thread
From: Paul E. McKenney @ 2019-10-05 19:35 UTC (permalink / raw)
  To: Jonathan Neuschäfer
  Cc: rcu, Josh Triplett, Steven Rostedt, Mathieu Desnoyers,
	Lai Jiangshan, Joel Fernandes, linux-kernel

On Sat, Oct 05, 2019 at 09:31:23PM +0200, Jonathan Neuschäfer wrote:
> On Sat, Oct 05, 2019 at 06:33:30AM -0700, Paul E. McKenney wrote:
> > On Sat, Oct 05, 2019 at 01:23:28AM +0200, Jonathan Neuschäfer wrote:
> > > On Fri, Oct 04, 2019 at 03:24:39PM -0700, Paul E. McKenney wrote:
> > > > On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> > > > > 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.)
> > 
> > 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:
> 
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -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.

You got it!  ;-)

							Thanx, Paul

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way
  2019-10-04 22:24 ` Paul E. McKenney
  2019-10-04 23:23   ` Jonathan Neuschäfer
@ 2019-10-06 23:44   ` Joel Fernandes
  1 sibling, 0 replies; 7+ messages in thread
From: Joel Fernandes @ 2019-10-06 23:44 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Jonathan Neuschäfer, rcu, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, linux-kernel

On Fri, Oct 04, 2019 at 03:24:39PM -0700, Paul E. McKenney wrote:
> On Fri, Oct 04, 2019 at 11:54:02PM +0200, Jonathan Neuschäfer wrote:
> > 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'
> > 
> > Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
> 
> 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


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-04 21:54 [PATCH] rculist: Describe variadic macro argument in a Sphinx-compatible way Jonathan Neuschäfer
2019-10-04 22:24 ` Paul E. McKenney
2019-10-04 23:23   ` Jonathan Neuschäfer
2019-10-05 13:33     ` Paul E. McKenney
2019-10-05 19:31       ` Jonathan Neuschäfer
2019-10-05 19:35         ` Paul E. McKenney
2019-10-06 23:44   ` Joel Fernandes

RCU Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/rcu/0 rcu/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 rcu rcu/ https://lore.kernel.org/rcu \
		rcu@vger.kernel.org rcu@archiver.kernel.org
	public-inbox-index rcu

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.rcu


AGPL code for this site: git clone https://public-inbox.org/ public-inbox