Improve watchdog API design using move semantics

[luojia65]

This pull request improved watchdog API design. When starting watchdog, we may convert it into another type. We may implement different functions for this type. Or downstream developers can implement Watchdog for only an enabled type, to prevent feed to disabled watchdogs or forget to enable before feeding. If we are able to stop this watchdog, it can be converted into the former type.

If current design still need a same type after the watchdog is enabled, they may use Target = Self. In this way we create a fallback for earlier designs.

A simple proof of concept: here (L120-L153 for its Enable implementation, and there is Disable implementation)

Related issue: #98
Earlier discussion: #76 (comment)

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @therealprof (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[therealprof]

Thanks for the PR. It looks good to me on first glance but I need to find time for a deeper review.

Two comments off the bat since you're touching this:

• We don't want to kick dogs anymore. 😅 Can we maybe change the kick into pet or something more friendly?
• Most watchdogs cannot be disabled once they've been armed/enabled so it would be great if we could mention that in the docs to not raise wrong expectations

[luojia65]

@therealprof Thank you! I've modified texts to avoid this word on dogs 😅 And additional documents are added to make it clear that, most watchdogs do not support disable process.

[eldruin]

A shortcoming of this approach is that a naive implementation of start or disable may drop the watchdog instance if the operation failed. I am unsure if that is always fine.
I have encountered this "fallible transformations" issue in several drivers where some methods transform the driver struct type (via a mode marker type) (e.g. from config status to operation status, which expose different methods) and my solution so far is to return the original instance through the error type.
Here is an example.
This would still be possible to do with this approach but in my attempts non-trivial error recovery code starts getting messier.

[luojia65]

@eldruin Thanks for comment! :) You're right, it's somehow tricky in error handling for failable type state classes. Seems like the only way is to return value in error type, but if I'm correct, this is common on Rust's std crate. For example if a RwLock or Mutex is poisoned when trying to lock, a PoisonError is returned; this type contains an into_inner function to return the guard back. As far as I know, there's rarely an error when enabling or disabling watchdogs; but if there are (for external watchdogs etc.), embedded drivers could still take this design to solve the problem.
I don't know if I'm correct, but this process is only complex on enabling, just like conventional type conversation methods. On feeding operation the code could be easy to write as it takes only &mut self.

[eldruin]

I added a couple comments but otherwise looks good to me.
@luojia65 could you rebase this to master and add an entry to the changelog?

[eldruin]

Thanks so far :)
I rephrased the changelog entry a bit to make it a bit clearer that the changes are not additional but the API has changed. Would this be fine with you @luojia65?
Additionally, could you squash the changes into one commit?

[eldruin]

Alright, this looks fine to me now.
Thank you @luojia65!

@therealprof ?

[therealprof]

LGTM!

[therealprof]

bors r+

[bors]

Build succeeded:

• ci-linux (stable, thumbv6m-none-eabi)
• ci-linux (stable, thumbv7m-none-eabi)
• ci-linux (stable, x86_64-unknown-linux-gnu)
• ci-linux (1.35.0, x86_64-unknown-linux-gnu)