linux-kernel - Re: [PATCH 0/2] kernel-doc: Remove deprecated kernel-doc option 'functions'

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <a6adae9df117daab7457260c030cc97d8608eccb.camel@sipsolutions.net>
Date: Tue, 23 Jan 2024 23:17:45 +0100
From: Johannes Berg <johannes@...solutions.net>
To: Jonathan Corbet <corbet@....net>, Anna-Maria Behnsen
	 <anna-maria@...utronix.de>, linux-doc@...r.kernel.org
Cc: Thomas Gleixner <tglx@...utronix.de>, Ingo Molnar <mingo@...hat.com>, 
 Borislav Petkov <bp@...en8.de>, x86@...nel.org, Mike Rapoport
 <rppt@...nel.org>, Herbert Xu <herbert@...dor.apana.org.au>, "David S.
 Miller" <davem@...emloft.net>,  Marco Elver <elver@...gle.com>, Alexander
 Potapenko <glider@...gle.com>, Shuah Khan <shuah@...nel.org>,  Moritz
 Fischer <mdf@...nel.org>, Wu Hao <hao.wu@...el.com>, Xu Yilun
 <yilun.xu@...el.com>,  Dipen Patel <dipenp@...dia.com>, Philipp Zabel
 <p.zabel@...gutronix.de>, Heikki Krogerus
 <heikki.krogerus@...ux.intel.com>, David Airlie <airlied@...il.com>, Daniel
 Vetter <daniel@...ll.ch>, Maarten Lankhorst
 <maarten.lankhorst@...ux.intel.com>, Maxime Ripard <mripard@...nel.org>,
 Thomas Zimmermann <tzimmermann@...e.de>, Jiri Kosina <jikos@...nel.org>,
 Benjamin Tissoires <benjamin.tissoires@...hat.com>, 
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH 0/2] kernel-doc: Remove deprecated kernel-doc option
 'functions'

On Tue, 2024-01-23 at 15:05 -0700, Jonathan Corbet wrote:
> 
> 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