Improve watchdog API design using move semantics

Co-authored-by: Diego Barrios Romero <[email protected]>

Co-authored-by: Daniel Egger <@therealprof:matrix.org>

Author: luojia65

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+
+- 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
 
 *** This is an alpha release with breaking changes (sorry) ***

src/prelude.rs

@@ -27,6 +27,6 @@ pub use crate::serial::Read as _embedded_hal_serial_Read;
 pub use crate::serial::Write as _embedded_hal_serial_Write;
 pub use crate::spi::FullDuplex as _embedded_hal_spi_FullDuplex;
 pub use crate::timer::CountDown as _embedded_hal_timer_CountDown;
-pub use crate::watchdog::Watchdog as _embedded_hal_watchdog_Watchdog;
 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;

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.
     ///
@@ -21,23 +21,28 @@ pub trait Enable {
     /// 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()`
+    /// 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. 
+    /// Starts the watchdog with a given period, typically once this is done
+    /// 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>(&mut self, period: T) -> Result<Self::Target, Self::Error>
+    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.
+///
+/// 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.
     ///
@@ -47,9 +52,9 @@ pub trait Disable {
     /// Disabled watchdog instance that can be enabled.
     type Target: Enable;
 
-    /// Disables the watchdog
+    /// Disables the watchdog.
     ///
-    /// This stops the watchdog and returns the `Enable` trait so that
-    /// it can be started again.
-    fn try_disable(&mut self) -> Result<Self::Target, Self::Error>;
+    /// 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>;
 }