mbox series

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

Message ID 20240122132820.46633-1-anna-maria@linutronix.de
Headers
Series kernel-doc: Remove deprecated kernel-doc option 'functions' |

Message

Anna-Maria Behnsen Jan. 22, 2024, 1:28 p.m. UTC 
  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(-)

Comments

Jiri Kosina Jan. 23, 2024, 10:46 a.m. UTC | #1 
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 <jkosina@suse.com>

I guess this will be all be merged by Jonathan in one go.

Thanks,
Johannes Berg Jan. 23, 2024, 10:53 a.m. UTC | #2 
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
Jonathan Corbet Jan. 23, 2024, 10:05 p.m. UTC | #3 
Johannes Berg <johannes@sipsolutions.net> 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
Johannes Berg Jan. 23, 2024, 10:17 p.m. UTC | #4 
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