Unclear documentation around disposing of DCMotor when used with MotorHat

[lloydjatkinson]

When using the Raspberry Pi MotorHat, the documentation shows a DCMotor being created but not disposed, only the MotorHat is being disposed of.

Looking at the MotorHat source, the underlying PwmChannel that is used to create the DCMotor is being disposed of when the MototHat is being disposed of. Additionally, the DCMotor2PinNoEnable type is also disposing of the PwmChannel that was passed to it when it was created.

It's not clear to me if this will cause some kind of conflict, and I'm not sure how to handle the current scenario:

    public class PumpController : IDisposable
    {
        private MotorHat _motorHat;
        private List<DCMotor> _motors = new List<DCMotor>;

        public void Initialise()
        {
            _motorHat = new MotorHat();
            _motors.Add(_motorHat.CreateDCMotor(1)); // simple example
        }

        ... do stuff with motors and timers

        public void Dispose()
        {
            _motorHat?.Dispose();
            foreach(var motor in _motors)
            {
                motor.Dispose();
            }
        }
    }

1. Does the order of disposing matter? Should the MotorHat be disposed of first or last?
2. Do the motors even need disposing of, given that the MotorHat disposes of the underlying PWM Channels?
3. If it is necessary to dispose of the motor hat and motors, is the above code the correct approach?

Right now I'm seeing a potential bug causing the MotorHat board being left in alternately inconsistent states if I close and restart my application, but not sure if this is because I'm not using the MotorHat correctly in the above code. If the above is correct I'll make a new issue specifically for the bug.

[krwq]

I believe intention is that multiple disposing is not going to cause any issues, please report if you're seeing any - I'll expect it will just work or you'll get an exception but not no randomness

[Ellerbach]

[Triage] Up to grab to make the docs even better!