Improve watchdog API design using move semantics

CHANGELOG.md

@@ -9,9 +9,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 ### Changed
+
 - The method `try_write` from the trait `blocking::i2c::WriteIter` trait
   has been renamed `try_write_iter` for consistency.
 - Updated `nb` dependency to version `1`.
+- The watchdog API now uses move semantics. See [PR](https://github.com/rust-embedded/embedded-hal/pull/222).
 
 ## [v1.0.0-alpha.1] - 2020-06-16
 

src/prelude.rs

@@ -34,6 +34,6 @@ pub use crate::spi::FullDuplex as _embedded_hal_spi_FullDuplex;
 pub use crate::timer::Cancel as _embedded_hal_timer_Cancel;
 pub use crate::timer::CountDown as _embedded_hal_timer_CountDown;
 pub use crate::timer::Periodic as _embedded_hal_timer_Periodic;
+pub use crate::watchdog::Disable as _embedded_hal_watchdog_Disable;
+pub use crate::watchdog::Enable as _embedded_hal_watchdog_Enable;
 pub use crate::watchdog::Watchdog as _embedded_hal_watchdog_Watchdog;
-pub use crate::watchdog::WatchdogDisable as _embedded_hal_watchdog_WatchdogDisable;
-pub use crate::watchdog::WatchdogEnable as _embedded_hal_watchdog_WatchdogEnable;

src/watchdog.rs

@@ -1,7 +1,7 @@
 //! Traits for interactions with a processors watchdog timer.
 
 /// Feeds an existing watchdog to ensure the processor isn't reset. Sometimes
-/// commonly referred to as "kicking" or "refreshing".
+/// the "feeding" operation is also referred to as "refreshing".
 pub trait Watchdog {
     /// An enumeration of `Watchdog` errors.
     ///
@@ -15,29 +15,46 @@ pub trait Watchdog {
 
 /// Enables A watchdog timer to reset the processor if software is frozen or
 /// stalled.
-pub trait WatchdogEnable {
-    /// An enumeration of `WatchdogEnable` errors.
+pub trait Enable {
+    /// An enumeration of `Enable` errors.
     ///
     /// For infallible implementations, will be `Infallible`
     type Error;
 
-    /// Unit of time used by the watchdog
+    /// Unit of time used by the watchdog.
     type Time;
 
+    /// The started watchdog that should be `feed()`.
+    type Target: Watchdog;
+
     /// Starts the watchdog with a given period, typically once this is done
-    /// the watchdog needs to be kicked periodically or the processor is reset.
-    fn try_start<T>(&mut self, period: T) -> Result<(), Self::Error>
+    /// the watchdog needs to be `feed()` periodically, or the processor would be
+    /// reset.
+    ///
+    /// This consumes the value and returns the `Watchdog` trait that you must
+    /// `feed()`.
+    fn try_start<T>(self, period: T) -> Result<Self::Target, Self::Error>
     where
         T: Into<Self::Time>;
 }
 
 /// Disables a running watchdog timer so the processor won't be reset.
-pub trait WatchdogDisable {
-    /// An enumeration of `WatchdogDisable` errors.
+///
+/// Not all watchdog timers support disable operation after they've been enabled.
+/// In this case, hardware support libraries would not implement this trait
+/// and hardware-agnostic libraries should consider not requiring it.
+pub trait Disable {
+    /// An enumeration of `Disable` errors.
     ///
     /// For infallible implementations, will be `Infallible`
     type Error;
 
-    /// Disables the watchdog
-    fn try_disable(&mut self) -> Result<(), Self::Error>;
+    /// Disabled watchdog instance that can be enabled.
+    type Target: Enable;
+
+    /// Disables the watchdog.
+    ///
+    /// This stops the watchdog and returns an instance implementing the
+    /// `Enable` trait so that it can be started again.
+    fn try_disable(self) -> Result<Self::Target, Self::Error>;
 }