[PATCH] rcu: fix kerneldoc comments in rcuupdate.h

[PATCH] rcu: fix kerneldoc comments in rcuupdate.h

[Tobias Klauser]

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

Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h

[Paul E. McKenney]

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
> 

Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h

[Tobias Klauser]

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

Re: [PATCH] rcu: fix kerneldoc comments in rcuupdate.h

[Tobias Klauser]

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