Hi,
the kernel-doc option 'functions' is marked deprecated and is simply an
alias for 'identifiers' and the conversion didn't looked that bad. So the
first patch replaces all existing users of 'functions' and the second
removes all parts in documentation and also inside the scripts.
Thanks,
Anna-Maria
Anna-Maria Behnsen (2):
Documentation: Replace deprecated 'functions' by 'identifiers'
Documentation: Remove deprecated kernel-doc option 'functions'
Documentation/PCI/pci.rst | 4 +-
Documentation/arch/x86/sgx.rst | 16 ++---
Documentation/core-api/boot-time-mm.rst | 2 +-
Documentation/core-api/debug-objects.rst | 14 ++--
Documentation/core-api/genalloc.rst | 34 +++++-----
Documentation/core-api/generic-radix-tree.rst | 2 +-
.../core-api/gfp_mask-from-fs-io.rst | 4 +-
Documentation/core-api/idr.rst | 4 +-
Documentation/core-api/kernel-api.rst | 12 ++--
Documentation/core-api/mm-api.rst | 6 +-
Documentation/core-api/printk-basics.rst | 4 +-
Documentation/crypto/api-aead.rst | 6 +-
Documentation/crypto/api-akcipher.rst | 6 +-
Documentation/crypto/api-digest.rst | 8 +--
Documentation/crypto/api-kpp.rst | 10 +--
Documentation/crypto/api-rng.rst | 4 +-
Documentation/crypto/api-skcipher.rst | 8 +--
Documentation/dev-tools/kcsan.rst | 6 +-
Documentation/dev-tools/kfence.rst | 10 +--
Documentation/dev-tools/kselftest.rst | 16 ++---
Documentation/doc-guide/kernel-doc.rst | 3 -
Documentation/driver-api/80211/cfg80211.rst | 16 ++---
.../driver-api/80211/mac80211-advanced.rst | 26 ++++----
Documentation/driver-api/80211/mac80211.rst | 12 ++--
Documentation/driver-api/device_link.rst | 2 +-
.../firmware/fallback-mechanisms.rst | 4 +-
.../driver-api/firmware/other_interfaces.rst | 10 +--
.../driver-api/firmware/request_firmware.rst | 14 ++--
Documentation/driver-api/fpga/fpga-bridge.rst | 8 +--
Documentation/driver-api/fpga/fpga-mgr.rst | 18 +++---
.../driver-api/fpga/fpga-programming.rst | 8 +--
Documentation/driver-api/fpga/fpga-region.rst | 22 +++----
Documentation/driver-api/hte/hte.rst | 4 +-
Documentation/driver-api/i2c.rst | 2 +-
Documentation/driver-api/infiniband.rst | 16 ++---
Documentation/driver-api/mei/hdcp.rst | 2 +-
Documentation/driver-api/reset.rst | 34 +++++-----
Documentation/driver-api/spi.rst | 2 +-
Documentation/driver-api/usb/typec.rst | 26 ++++----
Documentation/driver-api/usb/typec_bus.rst | 10 +--
.../gpu/amdgpu/display/display-manager.rst | 10 +--
Documentation/gpu/drm-kms-helpers.rst | 10 +--
Documentation/gpu/i915.rst | 64 +++++++++----------
Documentation/gpu/rfc/i915_scheduler.rst | 2 +-
Documentation/gpu/rfc/i915_small_bar.rst | 4 +-
Documentation/gpu/vga-switcheroo.rst | 14 ++--
Documentation/hid/hid-bpf.rst | 6 +-
Documentation/mm/ksm.rst | 2 +-
Documentation/security/tpm/tpm_vtpm_proxy.rst | 2 +-
Documentation/sphinx/kerneldoc.py | 5 --
50 files changed, 263 insertions(+), 271 deletions(-)
--
2.39.2
On Mon, 22 Jan 2024, Anna-Maria Behnsen wrote:
> the kernel-doc option 'functions' is marked deprecated and is simply an
> alias for 'identifiers' and the conversion didn't looked that bad. So the
> first patch replaces all existing users of 'functions' and the second
> removes all parts in documentation and also inside the scripts.
>
> Anna-Maria Behnsen (2):
> Documentation: Replace deprecated 'functions' by 'identifiers'
> Documentation: Remove deprecated kernel-doc option 'functions'
[ ... snip ... ]
> Documentation/hid/hid-bpf.rst | 6 +-
Acked-by: Jiri Kosina <[email protected]>
I guess this will be all be merged by Jonathan in one go.
Thanks,
--
Jiri Kosina
SUSE Labs
On Mon, 2024-01-22 at 14:28 +0100, Anna-Maria Behnsen wrote:
> the kernel-doc option 'functions' is marked deprecated and is simply an
> alias for 'identifiers'
Is it actually a good idea though that it's deprecated and an alias?
I mean, we have a problem today that sphinx/kernel-doc/whatever cannot
deal with having both
- struct cfg80211_rx_assoc_resp
- cfg80211_rx_assoc_resp()
I think at some point I found there's some kind of ticket open against
that, and while I don't hope it will be fixed soon (and we renamed that
struct because of it), maybe doing these changes will make it harder to
eventually deal with such a thing?
johannes
Johannes Berg <[email protected]> writes:
> On Mon, 2024-01-22 at 14:28 +0100, Anna-Maria Behnsen wrote:
>
>> the kernel-doc option 'functions' is marked deprecated and is simply an
>> alias for 'identifiers'
>
> Is it actually a good idea though that it's deprecated and an alias?
>
> I mean, we have a problem today that sphinx/kernel-doc/whatever cannot
> deal with having both
>
> - struct cfg80211_rx_assoc_resp
> - cfg80211_rx_assoc_resp()
>
> I think at some point I found there's some kind of ticket open against
> that, and while I don't hope it will be fixed soon (and we renamed that
> struct because of it), maybe doing these changes will make it harder to
> eventually deal with such a thing?
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?
Thanks,
jon
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