Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Sat, 5 Oct 2019 21:31:23 +0200
From:   Jonathan =?utf-8?Q?Neusch=C3=A4fer?= <j.neuschaefer@gmx.net>
To:     "Paul E. McKenney" <paulmck@kernel.org>
Cc:     Jonathan =?utf-8?Q?Neusch=C3=A4fer?= <j.neuschaefer@gmx.net>,
        rcu@vger.kernel.org, Josh Triplett <josh@joshtriplett.org>,
        Steven Rostedt <rostedt@goodmis.org>,
        Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
        Lai Jiangshan <jiangshanlai@gmail.com>,
        Joel Fernandes <joel@joelfernandes.org>,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH] rculist: Describe variadic macro argument in a
 Sphinx-compatible way
Message-ID: <20191005193123.GD19803@latitude>
References: <20191004215402.28008-1-j.neuschaefer@gmx.net>
 <20191004222439.GR2689@paulmck-ThinkPad-P72>
 <20191004232328.GC19803@latitude>
 <20191005133330.GX2689@paulmck-ThinkPad-P72>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
        protocol="application/pgp-signature"; boundary="SO98HVl1bnMOfKZd"
Content-Disposition: inline
In-Reply-To: <20191005133330.GX2689@paulmck-ThinkPad-P72>
User-Agent: Mutt/1.10.1 (2018-07-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk


--SO98HVl1bnMOfKZd
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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=C3=A4fer 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=C3=A4fer wr=
ote:
> > > > Without this patch, Sphinx shows "variable arguments" as the descri=
ption
> > > > of the cond argument, rather than the intended description, and pri=
nts
> > > > the following warnings:
> > > >=20
> > > > ./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'
> >=20
> > 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.
> >=20
> > So it may also be possible to fix the script instead. (I have not
> > looked into how much work that would be.)
>=20
> 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.
>=20
> 							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 =3D "...";
 	    }
+	    elsif ($param =3D~ /\w\.\.\.$/) {
+	      # for named variable parameters of the form `x...`, remove the dots
+	      $param =3D~ s/\.\.\.$//;
+	    }
 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq ""=
) {
 		$parameterdescs{$param} =3D "variable arguments";
 	    }

=2E.. 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=C3=A4fer

--SO98HVl1bnMOfKZd
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEvHAHGBBjQPVy+qvDCDBEmo7zX9sFAl2Y74EACgkQCDBEmo7z
X9seLBAApUhpXCs+cuFaUMDhWI3bq2Q0cDj+W9ZnnWTky3ACzDpWMaGdXQUeAIHG
dMB28qPTK3i+Jz1Ua9CBpTMnFZ1WYxNyXoxwWfL9kfLNZ3b3B1nQ0o1dlsD5W+Yt
ZpZNnazTlc+eV+qhtuU5Li0bql13Yflp30Hi7Xul/NttHfP17QUfqjKyg53+4+tE
1afWISDq4npnET4eZ3uQkcgxs+Q4IaCSeezIPQpicCgCrrVbXg+c79Lru5lhreU9
S/TLHymw1lwN3Nfvp1NDos3NleAR8N4s4pAcCOGzS8E73Hvrir6tUsxDfCB6JOie
6HYB5o7NdEHJHic6KKXSzVHcORCGh/SfAIstWqAVYhjMZqKjCUXIDkAkCWNOGy6Z
u0QLPW6oJG5AMB4k+kqQvaRYB6VMjjju/d+qFMtSf7Bq0NzCoD0N3c42fkLPiHcr
6rUaEiCYU/VeTBUM+RwkoPs47H6dmfhvjeaQvvEGoWEmwHJGBKhA2Y71cOUj7oWS
Vc+dWcCxBT2vSzgK8fARvBZgjNFnTNpDydNxukWHYRF3CXxwQXQ3JOnsQPG8rbXI
YnG/tKZOjzuFWMVA3kkGBNfpcBPfvYaKsQnfpl+or5Pu/JHywjhd50JwebMkHMBq
1MqhCraA45/lC2JgOcz+6a7AGxkSydeU/jvWQHifJXS6bBjETV4=
=LvVB
-----END PGP SIGNATURE-----

--SO98HVl1bnMOfKZd--