RCU Archive on lore.kernel.org
 help / color / Atom feed
From: Uladzislau Rezki <urezki@gmail.com>
To: Lukas Bulwahn <lukas.bulwahn@gmail.com>,
	"Paul E. McKenney" <paulmck@kernel.org>
Cc: Uladzislau Rezki <urezki@gmail.com>,
	Josh Triplett <josh@joshtriplett.org>,
	rcu@vger.kernel.org,
	"linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	Steven Rostedt <rostedt@goodmis.org>,
	Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
	Lai Jiangshan <jiangshanlai@gmail.com>,
	Joel Fernandes <joel@joelfernandes.org>
Subject: Re: kerneldoc warnings since commit 538fc2ee870a3 ("rcu: Introduce kfree_rcu() single-argument macro")
Date: Tue, 5 Jan 2021 14:14:41 +0100
Message-ID: <20210105131441.GA2457@pc638.lan> (raw)
In-Reply-To: <CAKXUXMygqbupE_6CK92=PwLw4DjnSuo9-+6iHs_DrZeZ55iRKg@mail.gmail.com>

Dear, Lukas.

> Dear Uladzislau,
> 
> in commit 538fc2ee870a3 ("rcu: Introduce kfree_rcu() single-argument
> macro"), you have refactored the kfree_rcu macro.
> 
> Since then, make htmldocs warns:
> 
> ./include/linux/rcupdate.h:882: warning: Excess function parameter
> 'ptr' description in 'kfree_rcu'
> ./include/linux/rcupdate.h:882: warning: Excess function parameter
> 'rhf' description in 'kfree_rcu'
> 
> As you deleted the two arguments in the macro definition, kerneldoc
> cannot resolve the argument names in the macro's kerneldoc
> documentation anymore and warns about that.
> 
> Probably, it is best to just turn the formal kerneldoc references to
> the two arguments, which are not used in the macro definition anymore,
> simply into two informal references in the documentation.
> 
Thanks for your suggestion. I am not sure if htmldocs supports something
like "__maybe_unused", but tend to say that it does not. See below the
patch:

<snip>
From 65ecc7c58810c963c02e0596ce2e5758c54ef55d Mon Sep 17 00:00:00 2001
From: "Uladzislau Rezki (Sony)" <urezki@gmail.com>
Date: Tue, 5 Jan 2021 13:23:30 +0100
Subject: [PATCH] rcu: fix kerneldoc warnings

After refactoring of the kfree_rcu(), it becomes possible to use
the macro with one or two arguments. From the other hand, in the
description there are two arguments in the macro definition expected.
That is why the "htmldocs" emits a warning about it:

<snip>
./include/linux/rcupdate.h:882: warning: Excess function parameter
'ptr' description in 'kfree_rcu'
./include/linux/rcupdate.h:882: warning: Excess function parameter
'rhf' description in 'kfree_rcu'
<snip>

Fix it by converting two parameters into informal references in the
macro description.

Fixes: 3d3d9ff077a9 ("rcu: Introduce kfree_rcu() single-argument macro")
Signed-off-by: Uladzislau Rezki (Sony) <urezki@gmail.com>
---
 include/linux/rcupdate.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
index ebd8dcca4997..e678ce7f5ca2 100644
--- a/include/linux/rcupdate.h
+++ b/include/linux/rcupdate.h
@@ -854,8 +854,8 @@ static inline notrace void rcu_read_unlock_sched_notrace(void)
 
 /**
  * kfree_rcu() - kfree an object after a grace period.
- * @ptr: pointer to kfree for both single- and double-argument invocations.
- * @rhf: the name of the struct rcu_head within the type of @ptr,
+ * ptr: pointer to kfree for both single- and double-argument invocations.
+ * rhf: the name of the struct rcu_head within the type of ptr,
  *       but only for double-argument invocations.
  *
  * Many rcu callbacks functions just call kfree() on the base structure.
-- 
2.20.1
<snip>

Paul, does it work for you?

Thanks!

--
Vlad Rezki

  reply index

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-05  7:32 Lukas Bulwahn
2021-01-05 13:14 ` Uladzislau Rezki [this message]
2021-01-05 14:03   ` Lukas Bulwahn
2021-01-05 14:56   ` Paul E. McKenney
2021-01-05 16:29     ` Uladzislau Rezki
2021-01-07  7:28       ` Lukas Bulwahn
2021-01-07 13:00         ` Uladzislau Rezki

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210105131441.GA2457@pc638.lan \
    --to=urezki@gmail.com \
    --cc=jiangshanlai@gmail.com \
    --cc=joel@joelfernandes.org \
    --cc=josh@joshtriplett.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=lukas.bulwahn@gmail.com \
    --cc=mathieu.desnoyers@efficios.com \
    --cc=paulmck@kernel.org \
    --cc=rcu@vger.kernel.org \
    --cc=rostedt@goodmis.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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