platform/surface: aggregator: Rename top-level request functions to avoid ambiguities
authorMaximilian Luz <luzmaximilian@gmail.com>
Tue, 20 Dec 2022 17:56:08 +0000 (18:56 +0100)
committerHans de Goede <hdegoede@redhat.com>
Thu, 2 Feb 2023 21:48:20 +0000 (22:48 +0100)
commitb09ee1cd59918bcf1a6793b663034b6e345b3ced
tree4e53e7792dff018ce809b3f71cbe19da1caba14d
parent13eca7d74e331deb5924ad0555355c114a59def2
platform/surface: aggregator: Rename top-level request functions to avoid ambiguities

We currently have a struct ssam_request_sync and a function
ssam_request_sync(). While this is valid C, there are some downsides to
it.

One of these is that current Sphinx versions (>= 3.0) cannot
disambiguate between the two (see disucssion and pull request linked
below). It instead emits a "WARNING: Duplicate C declaration" and links
for the struct and function in the resulting documentation link to the
same entry (i.e. both to either function or struct documentation)
instead of their respective own entries.

While we could just ignore that and wait for a fix, there's also a point
to be made that the current naming can be somewhat confusing when
searching (e.g. via grep) or trying to understand the levels of
abstraction at play:

We currently have struct ssam_request_sync and associated functions
ssam_request_sync_[alloc|free|init|wait|...]() operating on this struct.
However, function ssam_request_sync() is one abstraction level above
this. Similarly, ssam_request_sync_with_buffer() is not a function
operating on struct ssam_request_sync, but rather a sibling to
ssam_request_sync(), both using the struct under the hood.

Therefore, rename the top level request functions:

  ssam_request_sync() -> ssam_request_do_sync()
  ssam_request_sync_with_buffer() -> ssam_request_do_sync_with_buffer()
  ssam_request_sync_onstack() -> ssam_request_do_sync_onstack()

Link: https://lore.kernel.org/all/085e0ada65c11da9303d07e70c510dc45f21315b.1656756450.git.mchehab@kernel.org/
Link: https://github.com/sphinx-doc/sphinx/pull/8313
Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20221220175608.1436273-2-luzmaximilian@gmail.com
Reviewed-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
Documentation/driver-api/surface_aggregator/client.rst
drivers/hid/surface-hid/surface_hid.c
drivers/hid/surface-hid/surface_kbd.c
drivers/platform/surface/aggregator/bus.c
drivers/platform/surface/aggregator/controller.c
drivers/platform/surface/surface_acpi_notify.c
drivers/platform/surface/surface_aggregator_cdev.c
drivers/platform/surface/surface_aggregator_tabletsw.c
include/linux/surface_aggregator/controller.h
include/linux/surface_aggregator/device.h