[Proposal] Move classes and rename to be consistent throughout API

[shaggygi]

This proposal is a collection of different modifications and grouped here as there are many breaking changes being proposed. The intent is to review, decide and update (if needed) namespaces, class names and file locations in a consistent structure between the different types of interfaces within System.Device.Gpio API.

This seems to fit with @terrajobst comments during this design review, as well.

Rationale and Usage

Since System.Device.Gpio is in early previews, it seems like the opportune time to review and decide how to structure the core components. This will reduce breaking changes in the future.

Examples

• GPIO and PWM have abstract classes based on Drivers and are located under the *.Drivers folder. This includes RaspberryPi3Driver, UnixDriver.Linux.cs, etc.. Gpio is not in the file names where I2C/Pwm/SPI are included in the file names.
• I2C and SPI are based on Devices. However, there are implementations under the *.Drivers folders.

Proposed Changes

The proposed changes are to rename and move files as shown in the folder structure below. To simplify, this attempts to point out only the changes for the files being modified.

GPIO Folder

• TODO

1. Drivers and related classes renamed to include "Gpio".
2. GpioDriver.cs moved to Drivers folder.

Device
  Gpio
    Drivers
      GpioDriver.cs
      HummingBoardGpioDriver.cs
      HummingBoardGpioDriver.Linux.cs
      HummingBoardGpioDriver.Windows.cs
      RaspberryPi3GpioDriver.cs
      RaspberryPi3GpioDriver.Linux.cs
      RaspberryPi3GpioDriver.Windows.cs
      UnixGpioDriver.Linux.cs
      UnixGpioDriver.Windows.cs
      UnixGpioDriverPin.Linux.cs  // Also simplified by removing Device
      Windows10GpioDriver.Linux.cs
      Windows10GpioDriver.Windows.cs
      Windows10GpioDriverPin.Windows.cs
    GpioPinChangeEventHandler.cs
    GpioPinEventTypes.cs
    GpioPinMode.cs
    GpioPinNumberingScheme.cs
    GpioPinValue.cs
    GpioPinValueChangedEventArgs.cs

I2C Folder

• Completed in Rename i2c structure again #543

1. Folder renamed from "Drivers" to "Devices".
2. Namespaces be renamed from "System.Device.I2c.Drivers" to "System.Device.I2c"
3. I2cDevice.cs moved to Devices folder.

See #118 and #534 for related details

Device
  I2c
    Devices
      I2cDevice.cs
      I2cDevice.Linux.cs
      I2cDevice.Windows.cs
      [other devices here that were not moved or renamed]
    I2cConnectionSettings.cs (didn't change; showing for location purposes)

PWM Folder

• Completed in Better abstraction for PWM: PwmChannel #576

1. PwmDriver.cs moved to Drivers folder.

See #204 for related details

Device
  Pwm
    Drivers
      PwmDriver.cs

SPI Folder

• Completed in Rename SPI Structure #545

1. Folder renamed from "Drivers" to "Devices".
2. Namespaces be renamed from "System.Device.Spi.Drivers" to "System.Device.Spi"
3. SpiDevice.cs moved to Devices folder.

See #119 and #534 for related details

Device
  Spi
    Devices
      SpiDevice.cs
      SpiDevice.Linux.cs
      SpiDevice.Windows.cs
      [other devices here that were not moved or renamed]
    SpiConnectionSettings.cs (didn't change; showing for location purposes)

Open Questions

1. It seems a little redundant to have the interface in the file name. For example, GpioPinMode. Is this too redundant knowing it is under the Gpio folder/namespace? It seems like differentiating would be okay, especially when mixing different pin types in code files (e.g. Bindings with a mixture of digital, analog and PWM pins). This would help when adding "usings" or typing entire namespace out.

[shaggygi]

@joshfree @joperezr Just wanted to ping this one again now that Preview 2 is out.

[joperezr]

Hey @shaggygi thanks for bringing up all of these good questions. I do agree that there are some inconsistencies across our library today, which should get fixed before we ship a stable package. For example, I don't like the fact that Gpio and PWM have a controller which is what you interact with and don't have a specific device object (which in this case would be a GpioPin or PwmPin) but in I2c and Spi we do have the individual devices and don't have a controller for the whole bus. I also think we are lacking some behavior interfaces which should be added which those are tracked by other issues.

In general for your other questions, I don't think that adding Gpio into all of the classnames under Gpio makes sense as since you point out, it does add redundancy when you see the fully qualified name. That said, we do have some counter-examples for that. Let's keep this issue around and use it to discuss concrete examples that should change for the next previews so that we can make things more consistent.

[shaggygi]

Sounds good. It might be worth to keep some action items (checkboxes) on this as the main place to confirm the overall API changes that need to happen to call it complete (even if there are other issues created for specific action items).

I agree the namespaces help separate out (although preferred to include). I just want to make sure (if possible) to make different sections close that make sense. As noted... I'm okay with System.Device.Gpio.UnixDriver, but we should also have System.Device.Pwm.UnixDriver.

And while using the namespace to separate will help, I'm more worried when we begin working on future interfaces and implement bindings that have multiple functions. For example, now that the IGpioController is pushed, I plan to begin working on a new binding that provides GPIO and PWM. The plan is to later add what is pushed for IPwmController (or related solution). By not having the function in name, it might get a little confusing like the UnixDriver example as we could be using both.

Thanks again for managing this... it's a booger 😄