Received-SPF: pass (google.com: domain of linux-kernel+bounces-36127-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Message-ID: <a6adae9df117daab7457260c030cc97d8608eccb.camel@sipsolutions.net>
Subject: Re: [PATCH 0/2] kernel-doc: Remove deprecated kernel-doc option
 'functions'
From: Johannes Berg <johannes@sipsolutions.net>
To: Jonathan Corbet <corbet@lwn.net>, Anna-Maria Behnsen
	 <anna-maria@linutronix.de>, linux-doc@vger.kernel.org
Cc: Thomas Gleixner <tglx@linutronix.de>, Ingo Molnar <mingo@redhat.com>, 
 Borislav Petkov <bp@alien8.de>, x86@kernel.org, Mike Rapoport
 <rppt@kernel.org>, Herbert Xu <herbert@gondor.apana.org.au>, "David S.
 Miller" <davem@davemloft.net>,  Marco Elver <elver@google.com>, Alexander
 Potapenko <glider@google.com>, Shuah Khan <shuah@kernel.org>,  Moritz
 Fischer <mdf@kernel.org>, Wu Hao <hao.wu@intel.com>, Xu Yilun
 <yilun.xu@intel.com>,  Dipen Patel <dipenp@nvidia.com>, Philipp Zabel
 <p.zabel@pengutronix.de>, Heikki Krogerus
 <heikki.krogerus@linux.intel.com>, David Airlie <airlied@gmail.com>, Daniel
 Vetter <daniel@ffwll.ch>, Maarten Lankhorst
 <maarten.lankhorst@linux.intel.com>, Maxime Ripard <mripard@kernel.org>,
 Thomas Zimmermann <tzimmermann@suse.de>, Jiri Kosina <jikos@kernel.org>,
 Benjamin Tissoires <benjamin.tissoires@redhat.com>, 
 linux-kernel@vger.kernel.org
Date: Tue, 23 Jan 2024 23:17:45 +0100
In-Reply-To: <87y1cfiu2y.fsf@meer.lwn.net>
References: <20240122132820.46633-1-anna-maria@linutronix.de>
	 <c0fd30e8e6d175eab50d7d5212117107e5251e4d.camel@sipsolutions.net>
	 <87y1cfiu2y.fsf@meer.lwn.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.50.3 (3.50.3-1.fc39) 
Precedence: bulk
MIME-Version: 1.0

On Tue, 2024-01-23 at 15:05 -0700, Jonathan Corbet wrote:
>=20
> So I feel like I'm missing something; the problem with Sphinx and
> namespacing is separate from whether kernel-doc recognizes "-functions";
> I don't think that taking out this support will make the other problem
> any harder to solve.  Do you see something I'm not?

Well, I was thinking that today, in the rst files, we use

. kernel-doc:: include/net/cfg80211.h
   :functions:
        cfg80211_rx_assoc_resp

(for example).

This clearly references the *function* cfg80211_rx_assoc_resp(), at
least it makes that intent clear.

We also had a *struct* called cfg80211_rx_assoc_resp, until we removed
it recently because of the sphinx namespacing issues.


Now if we change the reference to the function to be just

. kernel-doc:: include/net/cfg80211.h
   :identifiers:
        cfg80211_rx_assoc_resp

then how do you know that it's actually referencing the function vs. the
struct? I mean, OK, today it can only reference the single "thing" (**)
that sphinx accepts ...  but hoping that some day the sphinx namespacing
issue will be solved, we'd need a way to actually reference the
different namespaces from the rst files, no? So it seemed to me that
just unconditionally referencing an "identifier" makes that harder, not
easier?

We have 'struct class' for example, and use

. kernel-doc:: include/linux/device/class.h
   :identifiers: class

to refer to it. At least you know it's not a function, though if you
also had an 'enum class' you'd not be able to figure it out.


(**) Also, I think a struct or enum name isn't actually called an
identifier in C? So maybe that's a bad term regardless of the
namespacing. But I guess even if I'm right (and I'm not really sure)
then that's too late now.

johannes