From 6f8266c02f2acd6ff3d678016308fd1e6377f791 Mon Sep 17 00:00:00 2001 From: Filip Jagodzinski Date: Wed, 3 Jul 2019 15:28:37 +0200 Subject: [PATCH 1/3] Watchdog: Clean up the doxygen comments --- drivers/Watchdog.h | 89 +++++++++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/drivers/Watchdog.h b/drivers/Watchdog.h index 5d4126e965c..6aee4f72266 100644 --- a/drivers/Watchdog.h +++ b/drivers/Watchdog.h @@ -30,14 +30,23 @@ namespace mbed { /** \addtogroup drivers */ -/** Hardware system timer that will reset the system in the case of system failures or - * malfunctions. There is only one instance in the system. +/** A hardware watchdog timer that will reset the system in the case of system + * failures or malfunctions. If you fail to refresh the Watchdog periodically, + * it will reset the system after a set period of time. + * + * There is only one instance in the system. Use Watchdog::get_instance to + * obtain a reference. + * + * Watchdog::start initializes a system timer with a time period specified in + * @a timeout param. This timer counts down and triggers a system reset + * when it wraps. To prevent the system reset, the timer must be continually + * kicked/refreshed by calling Watchdog::kick, which will reset the countdown + * to the user specified reset value. * * Example: * @code - * * Watchdog &watchdog = Watchdog::get_instance(); - * watchdog.start(); + * watchdog.start(500); * * while (true) { // kick watchdog regularly within provided timeout @@ -52,9 +61,13 @@ namespace mbed { class Watchdog : private NonCopyable { public: - /** As Watchdog might not stop ever, there is just one instance - we use single instance. - * This ensures we keep Watchdog alive. To operate watchdog, use start/stop methods. - */ + /** Get a reference to the single Watchdog instance in the system. + * + * There is only one watchdog peripheral and only one Watchdog instance + * to control it. + * + * @return A reference to the single Watchdog instance present in the system. + */ static Watchdog &get_instance() { // Use this implementation of singleton (Meyer's) rather than the one that allocates @@ -64,61 +77,71 @@ class Watchdog : private NonCopyable { return instance; } - /** Start the watchdog timer with the maximum timeout available on a target + /** Start the Watchdog timer with the maximum timeout value available for + * the target. + * + * @note The timeout is set to a value returned by Watchdog::get_max_timeout. * - * Timeout is defined as get_max_timeout() + * If the Watchdog is already running, this function does nothing. * - * @return status true if the watchdog timer was started - * successfully. assert if one of the input parameters is out of range for the current platform. - * false if watchdog timer was not started + * @return true, if the Watchdog timer was started successfully, + * false, if Watchdog timer was not started or if the Watchdog + * is already running. */ bool start(); - /** Start the watchdog timer + /** Start the Watchdog timer. * - * @param timeout Watchdog timeout + * @note Asset that the timeout param is supported by the target + * (0 < timeout <= Watchdog::get_max_timeout). * - * @return status true if the watchdog timer was started - * successfully. assert if one of the input parameters is out of range for the current platform. - * false if watchdog timer was not started + * @param timeout Watchdog timeout in milliseconds. + * + * @return true, if the Watchdog timer was started successfully, + * false, if Watchdog timer was not started or if the Watchdog + * is already running. */ bool start(uint32_t timeout); - /** Stops the watchdog timer + /** Stop the Watchdog timer. * - * Calling this function will attempt to disable any currently running - * watchdog timers if supported by the current platform. + * Calling this function will attempt to disable a running Watchdog + * peripheral if supported by the platform. * - * @return Returns true if the watchdog timer was successfully - * stopped, Returns false if the watchdog cannot be disabled - * on the current platform or if the timer was never started. + * @return true, if the Watchdog timer was successfully stopped, + * false, if the Watchdog cannot be disabled on this platform + * or if the Watchdog has not been started. */ bool stop(); - /** Get the watchdog timer refresh value + /** Get the Watchdog timer refresh value. * - * This function returns the refresh timeout of the watchdog timer. + * This function returns the refresh timeout of the watchdog peripheral. * - * @return Reload value for the watchdog timer in milliseconds. + * @return Reload value for the Watchdog timer in milliseconds. */ uint32_t get_timeout() const; - /** Get the maximum refresh value for the current platform in milliseconds + /** Get the maximum Watchdog refresh value for this platform. * - * @return Maximum refresh value supported by the watchdog for the current - * platform in milliseconds + * @return Maximum reload value supported by the Watchdog timer for this + * platform in milliseconds. */ uint32_t get_max_timeout() const; - /** Check if watchdog is already running + /** Check if the Watchdog is already running. * - * @return true if watchdog is running, false otherwise + * @return true, if the Watchdog is running, + * false, otherwise. */ bool is_running() const; - /** Kick watchdog + /** Refresh the Watchdog timer. + * + * Call this function periodically before the Watchdog times out. + * Otherwise, the system is reset. * - * This method is useful to control kicking by application in ticker callback periodically + * If the Watchdog is not running, this function does nothing. */ void kick(); From ec53d1d9c85fb15b722fb006474d67cf5770065f Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 3 Jul 2019 17:43:51 -0500 Subject: [PATCH 2/3] Edit Watchdog.h Edit file to address comments and for consistent tense and voice. --- drivers/Watchdog.h | 53 ++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 28 deletions(-) diff --git a/drivers/Watchdog.h b/drivers/Watchdog.h index 6aee4f72266..5db5f82defe 100644 --- a/drivers/Watchdog.h +++ b/drivers/Watchdog.h @@ -30,18 +30,18 @@ namespace mbed { /** \addtogroup drivers */ -/** A hardware watchdog timer that will reset the system in the case of system - * failures or malfunctions. If you fail to refresh the Watchdog periodically, - * it will reset the system after a set period of time. +/** A hardware watchdog timer that resets the system in the case of system + * failures or malfunctions. If you fail to refresh the Watchdog timer periodically, + * it resets the system after a set period of time. * - * There is only one instance in the system. Use Watchdog::get_instance to - * obtain a reference. + * There is only one instance of the Watchdog class in the system, which directly maps to the hardware. + * Use Watchdog::get_instance to obtain a reference. * * Watchdog::start initializes a system timer with a time period specified in * @a timeout param. This timer counts down and triggers a system reset - * when it wraps. To prevent the system reset, the timer must be continually - * kicked/refreshed by calling Watchdog::kick, which will reset the countdown - * to the user specified reset value. + * when it wraps. To prevent the system reset, you must periodically kick or refresh + * the timer by calling Watchdog::kick, which resets the countdown + * to the initial value. * * Example: * @code @@ -62,9 +62,6 @@ class Watchdog : private NonCopyable { public: /** Get a reference to the single Watchdog instance in the system. - * - * There is only one watchdog peripheral and only one Watchdog instance - * to control it. * * @return A reference to the single Watchdog instance present in the system. */ @@ -82,11 +79,11 @@ class Watchdog : private NonCopyable { * * @note The timeout is set to a value returned by Watchdog::get_max_timeout. * - * If the Watchdog is already running, this function does nothing. + * If the Watchdog timer is already running, this function does nothing. * - * @return true, if the Watchdog timer was started successfully, - * false, if Watchdog timer was not started or if the Watchdog - * is already running. + * @return true if the Watchdog timer was started successfully; + * false if the Watchdog timer was not started or if the Watchdog + * timer is already running. */ bool start(); @@ -97,20 +94,20 @@ class Watchdog : private NonCopyable { * * @param timeout Watchdog timeout in milliseconds. * - * @return true, if the Watchdog timer was started successfully, - * false, if Watchdog timer was not started or if the Watchdog - * is already running. + * @return true if the Watchdog timer was started successfully; + * false if Watchdog timer was not started or if the Watchdog + * timer is already running. */ bool start(uint32_t timeout); /** Stop the Watchdog timer. * - * Calling this function will attempt to disable a running Watchdog - * peripheral if supported by the platform. + * Calling this function disables a running Watchdog + * peripheral if the platform supports it. * - * @return true, if the Watchdog timer was successfully stopped, - * false, if the Watchdog cannot be disabled on this platform - * or if the Watchdog has not been started. + * @return true if the Watchdog timer was successfully stopped; + * false if the Watchdog timer cannot be disabled on this platform + * or if the Watchdog timer has not been started. */ bool stop(); @@ -129,19 +126,19 @@ class Watchdog : private NonCopyable { */ uint32_t get_max_timeout() const; - /** Check if the Watchdog is already running. + /** Check if the Watchdog timer is already running. * - * @return true, if the Watchdog is running, - * false, otherwise. + * @return true if the Watchdog timer is running and + * false otherwise. */ bool is_running() const; /** Refresh the Watchdog timer. * * Call this function periodically before the Watchdog times out. - * Otherwise, the system is reset. + * Otherwise, the system resets. * - * If the Watchdog is not running, this function does nothing. + * If the Watchdog timer is not running, this function does nothing. */ void kick(); From 0f3f38e512f042dd79698f2db02fee6c5f73be16 Mon Sep 17 00:00:00 2001 From: Filip Jagodzinski Date: Thu, 4 Jul 2019 10:49:24 +0200 Subject: [PATCH 3/3] Watchdog: Fix astyle in doxy --- drivers/Watchdog.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/Watchdog.h b/drivers/Watchdog.h index 5db5f82defe..495965d3901 100644 --- a/drivers/Watchdog.h +++ b/drivers/Watchdog.h @@ -34,7 +34,7 @@ namespace mbed { * failures or malfunctions. If you fail to refresh the Watchdog timer periodically, * it resets the system after a set period of time. * - * There is only one instance of the Watchdog class in the system, which directly maps to the hardware. + * There is only one instance of the Watchdog class in the system, which directly maps to the hardware. * Use Watchdog::get_instance to obtain a reference. * * Watchdog::start initializes a system timer with a time period specified in