RCU Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] rcu: fix kerneldoc comments in rcuupdate.h
@ 2020-07-02 16:25 Tobias Klauser
  2020-07-02 17:06 ` Paul E. McKenney
  0 siblings, 1 reply; 4+ messages in thread
From: Tobias Klauser @ 2020-07-02 16:25 UTC (permalink / raw)
  To: Paul E. McKenney, Josh Triplett; +Cc: rcu

Fix the kerneldoc comments for rcu_read_unlock_bh(),
rcu_read_unlock_sched() and rcu_head_after_call_rcu() so they e.g. get
properly linked in the API documentation.

Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
---
 include/linux/rcupdate.h | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
index d15d46db61f7..b47d6b66665e 100644
--- a/include/linux/rcupdate.h
+++ b/include/linux/rcupdate.h
@@ -709,8 +709,8 @@ static inline void rcu_read_lock_bh(void)
 			 "rcu_read_lock_bh() used illegally while idle");
 }
 
-/*
- * rcu_read_unlock_bh - marks the end of a softirq-only RCU critical section
+/**
+ * rcu_read_unlock_bh() - marks the end of a softirq-only RCU critical section
  *
  * See rcu_read_lock_bh() for more information.
  */
@@ -751,10 +751,10 @@ static inline notrace void rcu_read_lock_sched_notrace(void)
 	__acquire(RCU_SCHED);
 }
 
-/*
- * rcu_read_unlock_sched - marks the end of a RCU-classic critical section
+/**
+ * rcu_read_unlock_sched() - marks the end of a RCU-classic critical section
  *
- * See rcu_read_lock_sched for more information.
+ * See rcu_read_lock_sched() for more information.
  */
 static inline void rcu_read_unlock_sched(void)
 {
@@ -945,7 +945,7 @@ static inline void rcu_head_init(struct rcu_head *rhp)
 }
 
 /**
- * rcu_head_after_call_rcu - Has this rcu_head been passed to call_rcu()?
+ * rcu_head_after_call_rcu() - Has this rcu_head been passed to call_rcu()?
  * @rhp: The rcu_head structure to test.
  * @f: The function passed to call_rcu() along with @rhp.
  *
-- 
2.27.0


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

* Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h
  2020-07-02 16:25 [PATCH] rcu: fix kerneldoc comments in rcuupdate.h Tobias Klauser
@ 2020-07-02 17:06 ` Paul E. McKenney
  2020-07-02 19:43   ` Tobias Klauser
  2020-07-09 13:09   ` Tobias Klauser
  0 siblings, 2 replies; 4+ messages in thread
From: Paul E. McKenney @ 2020-07-02 17:06 UTC (permalink / raw)
  To: Tobias Klauser; +Cc: Josh Triplett, rcu

On Thu, Jul 02, 2020 at 06:25:57PM +0200, Tobias Klauser wrote:
> Fix the kerneldoc comments for rcu_read_unlock_bh(),
> rcu_read_unlock_sched() and rcu_head_after_call_rcu() so they e.g. get
> properly linked in the API documentation.
> 
> Signed-off-by: Tobias Klauser <tklauser@distanz.ch>

The addition of the second "*" is clearly needed, good eyes and thank you!
But where do these entries link to?  As in does adding the "()" link
somewhere else, and if so, where?  If it instead links to the entry
created by the corresponding docbook comment, is that really helpful?

What am I missing here?

							Thanx, Paul

> ---
>  include/linux/rcupdate.h | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
> index d15d46db61f7..b47d6b66665e 100644
> --- a/include/linux/rcupdate.h
> +++ b/include/linux/rcupdate.h
> @@ -709,8 +709,8 @@ static inline void rcu_read_lock_bh(void)
>  			 "rcu_read_lock_bh() used illegally while idle");
>  }
>  
> -/*
> - * rcu_read_unlock_bh - marks the end of a softirq-only RCU critical section
> +/**
> + * rcu_read_unlock_bh() - marks the end of a softirq-only RCU critical section
>   *
>   * See rcu_read_lock_bh() for more information.
>   */
> @@ -751,10 +751,10 @@ static inline notrace void rcu_read_lock_sched_notrace(void)
>  	__acquire(RCU_SCHED);
>  }
>  
> -/*
> - * rcu_read_unlock_sched - marks the end of a RCU-classic critical section
> +/**
> + * rcu_read_unlock_sched() - marks the end of a RCU-classic critical section
>   *
> - * See rcu_read_lock_sched for more information.
> + * See rcu_read_lock_sched() for more information.
>   */
>  static inline void rcu_read_unlock_sched(void)
>  {
> @@ -945,7 +945,7 @@ static inline void rcu_head_init(struct rcu_head *rhp)
>  }
>  
>  /**
> - * rcu_head_after_call_rcu - Has this rcu_head been passed to call_rcu()?
> + * rcu_head_after_call_rcu() - Has this rcu_head been passed to call_rcu()?
>   * @rhp: The rcu_head structure to test.
>   * @f: The function passed to call_rcu() along with @rhp.
>   *
> -- 
> 2.27.0
> 

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

* Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h
  2020-07-02 17:06 ` Paul E. McKenney
@ 2020-07-02 19:43   ` Tobias Klauser
  2020-07-09 13:09   ` Tobias Klauser
  1 sibling, 0 replies; 4+ messages in thread
From: Tobias Klauser @ 2020-07-02 19:43 UTC (permalink / raw)
  To: Paul E. McKenney; +Cc: Josh Triplett, rcu

On 2020-07-02 at 19:06:04 +0200, Paul E. McKenney <paulmck@kernel.org> wrote:
> On Thu, Jul 02, 2020 at 06:25:57PM +0200, Tobias Klauser wrote:
> > Fix the kerneldoc comments for rcu_read_unlock_bh(),
> > rcu_read_unlock_sched() and rcu_head_after_call_rcu() so they e.g. get
> > properly linked in the API documentation.
> > 
> > Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
> 
> The addition of the second "*" is clearly needed, good eyes and thank you!
> But where do these entries link to?  As in does adding the "()" link
> somewhere else, and if so, where?  If it instead links to the entry
> created by the corresponding docbook comment, is that really helpful?
> 
> What am I missing here?

Adding the "()" doesn't change anything with regards to whether a link
gets created and where it points to, as far as I can tell. I mainly
changed these to be consistent with the kerneldoc comments for other
functions in the same file, which all use the "()" notation. Sorry, I
should have mentioned that in the commit message.

I can drop this part from the patch or send a patch with a revised
commit message if you prefer.

Thanks
Tobias

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

* Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h
  2020-07-02 17:06 ` Paul E. McKenney
  2020-07-02 19:43   ` Tobias Klauser
@ 2020-07-09 13:09   ` Tobias Klauser
  1 sibling, 0 replies; 4+ messages in thread
From: Tobias Klauser @ 2020-07-09 13:09 UTC (permalink / raw)
  To: Paul E. McKenney; +Cc: Josh Triplett, rcu

Hi Paul

On 2020-07-02 at 19:06:04 +0200, Paul E. McKenney <paulmck@kernel.org> wrote:
> On Thu, Jul 02, 2020 at 06:25:57PM +0200, Tobias Klauser wrote:
> > Fix the kerneldoc comments for rcu_read_unlock_bh(),
> > rcu_read_unlock_sched() and rcu_head_after_call_rcu() so they e.g. get
> > properly linked in the API documentation.
> > 
> > Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
> 
> The addition of the second "*" is clearly needed, good eyes and thank you!
> But where do these entries link to?  As in does adding the "()" link
> somewhere else, and if so, where?  If it instead links to the entry
> created by the corresponding docbook comment, is that really helpful?
> 
> What am I missing here?

I've sent v2 of the patch [1] which amends the commit message to mention
which the "()" were added.

[1] https://lore.kernel.org/rcu/20200709130559.25588-1-tklauser@distanz.ch/

As noted in the previous message [2], adding the "()" doesn't change
anything with regards to whether a link gets created and where it points
to. Thus, I mentiond in the v2 commit message that this is only for
consistency with kerneldoc comments of other functions in the same file.

[2] https://lore.kernel.org/rcu/20200702194306.uc4sumrk7ahuk23l@distanz.ch/

Thanks
Tobias

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

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-02 16:25 [PATCH] rcu: fix kerneldoc comments in rcuupdate.h Tobias Klauser
2020-07-02 17:06 ` Paul E. McKenney
2020-07-02 19:43   ` Tobias Klauser
2020-07-09 13:09   ` Tobias Klauser

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
	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.git