Merge pull request #10954 from fkjagodzinski/docs_update-watchdog_driver

Watchdog: Clean up the doxygen comments

Author: 0xc0170

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 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 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, you must periodically kick or refresh
+ * the timer by calling Watchdog::kick, which resets the countdown
+ * to the initial value.
  *
  * Example:
  * @code
- *
  * Watchdog &watchdog = Watchdog::get_instance();
- * watchdog.start();
+ * watchdog.start(500);
  *
  * while (true) {
       // kick watchdog regularly within provided timeout
@@ -52,9 +61,10 @@ namespace mbed {
 class Watchdog : private NonCopyable<Watchdog>  {
 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.
+     *
+     * @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 +74,71 @@ class Watchdog : private NonCopyable<Watchdog>  {
         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 timer 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 the Watchdog timer was not started or if the Watchdog
+     *         timer 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
+     *         timer 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 disables a running Watchdog
+     * peripheral if the platform supports it.
      *
-     * @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 timer cannot be disabled on this platform
+     *         or if the Watchdog timer 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 timer is already running.
      *
-     * @return true if watchdog is running, false otherwise
+     * @return true if the Watchdog timer is running and
+     *         false otherwise.
      */
     bool is_running() const;
 
-    /** Kick watchdog
+    /** Refresh the Watchdog timer.
+     *
+     * Call this function periodically before the Watchdog times out.
+     * Otherwise, the system resets.
      *
-     * This method is useful to control kicking by application in ticker callback periodically
+     * If the Watchdog timer is not running, this function does nothing.
      */
     void kick();