diff mbox series

[v2,2/3] docs: consolidate peripheral interfaces

Message ID 20230722113253.1545231-1-costa.shul@redhat.com
State New
Headers
Series None |

Commit Message

Costa Shulyupin July 22, 2023, 11:32 a.m. UTC 
  to make page Subsystems APIs more organized as requested

Changes:
v2: added pcmcia and subtitle

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

---

Alternative consolidation of buses look more challenging.
Here are too many buses, so them should be split again.
Many of buses are specific for only x86 or only embedded computers.
Is SCSI generic bus or storage bus?
---
 Documentation/subsystem-apis.rst | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

Comments

Jonathan Corbet July 24, 2023, 4:16 p.m. UTC | #1 
Costa Shulyupin <costa.shul@redhat.com> writes:

> to make page Subsystems APIs more organized as requested
>
> Changes:
> v2: added pcmcia and subtitle
>
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
>
> ---
>
> Alternative consolidation of buses look more challenging.
> Here are too many buses, so them should be split again.
> Many of buses are specific for only x86 or only embedded computers.
> Is SCSI generic bus or storage bus?
> ---
>  Documentation/subsystem-apis.rst | 19 ++++++++++++++-----
>  1 file changed, 14 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 90a0535a932a..5ace1c434977 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -48,6 +48,20 @@ Networking interfaces
>     isdn/index
>     mhi/index
>  
> +Peripheral interfaces
> +----------------------
> +
> +except specific networking and storage interfaces
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   usb/index
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +   pcmcia/index
> +
>  Storage interfaces
>  ------------------
>  
> @@ -70,19 +84,14 @@ Storage interfaces
>     fpga/index
>     i2c/index
>     iio/index
> -   leds/index
> -   pcmcia/index
>     spi/index
>     w1/index
>     watchdog/index
>     virt/index
> -   hwmon/index
>     accel/index
>     security/index
>     crypto/index
>     bpf/index
> -   usb/index
> -   PCI/index
>     misc-devices/index
>     peci/index
>     wmi/index

I'm sorry, but I feel like you've missed the point here - adding PCMCIA
doesn't really address my concern at all.  What is a "peripheral
interface", and how does USB qualify but, say, SPI does not?  I feel
like we have stopped adding clarity at this point.

A lot of this documentation needs a closer look to think about how it
fits into our model.  As a quick example (and an example only), the LED
documentation would appear to be properly placed in the userspace-api
guide, not in this grab-bag section.  Just shuffling it around in the
file doesn't help address problems like that, unfortunately.

Thanks,

jon
diff mbox series

Patch

diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
index 90a0535a932a..5ace1c434977 100644
--- a/Documentation/subsystem-apis.rst
+++ b/Documentation/subsystem-apis.rst
@@ -48,6 +48,20 @@  Networking interfaces
    isdn/index
    mhi/index
 
+Peripheral interfaces
+----------------------
+
+except specific networking and storage interfaces
+
+.. toctree::
+   :maxdepth: 1
+
+   usb/index
+   PCI/index
+   hwmon/index
+   leds/index
+   pcmcia/index
+
 Storage interfaces
 ------------------
 
@@ -70,19 +84,14 @@  Storage interfaces
    fpga/index
    i2c/index
    iio/index
-   leds/index
-   pcmcia/index
    spi/index
    w1/index
    watchdog/index
    virt/index
-   hwmon/index
    accel/index
    security/index
    crypto/index
    bpf/index
-   usb/index
-   PCI/index
    misc-devices/index
    peci/index
    wmi/index