[PATCH 2/3] docs: consolidate peripheral interfaces

[PATCH 2/3] docs: consolidate peripheral interfaces

[Costa Shulyupin]

to make the page more organized as requested

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
---
 Documentation/subsystem-apis.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
index 90a0535a932a..7b086c89e2be 100644
--- a/Documentation/subsystem-apis.rst
+++ b/Documentation/subsystem-apis.rst
@@ -48,6 +48,17 @@ Networking interfaces
    isdn/index
    mhi/index
 
+Peripheral interfaces
+----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   usb/index
+   PCI/index
+   hwmon/index
+   leds/index
+
 Storage interfaces
 ------------------
 
@@ -70,19 +81,15 @@ 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
-- 
2.41.0

Re: [PATCH 2/3] docs: consolidate peripheral interfaces

[Jonathan Corbet]

Costa Shulyupin <costa.shul@redhat.com> writes:

> to make the page more organized as requested
>
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
> ---
>  Documentation/subsystem-apis.rst | 15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 90a0535a932a..7b086c89e2be 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -48,6 +48,17 @@ Networking interfaces
>     isdn/index
>     mhi/index
>  
> +Peripheral interfaces
> +----------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   usb/index
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +
>  Storage interfaces
>  ------------------
>  
> @@ -70,19 +81,15 @@ 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

So this one seems a bit less well thought out.  How are you defining
"peripheral interface"?  How is it that PCI qualifies but, say, PCMCIA
does not?  In a real sense, most of our interfaces deal with peripherals
in one way or another.

Were you thinking maybe of "bus interfaces"?  If so, a somewhat
different selection would be indicated.

Thanks,

jon

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

[Costa Shulyupin]

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
-- 
2.41.0

Re: [PATCH v2 2/3] docs: consolidate peripheral interfaces

[Jonathan Corbet]

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