From dc5b8a2c7fe5e89c722674db6ee797c5cc637da1 Mon Sep 17 00:00:00 2001
From: recan-li <721317716@qq.com>
Date: Tue, 30 Mar 2021 17:14:38 +0800
Subject: [PATCH] fix: Fix timer_stop logic && add more comment

---
 multi_timer.c | 45 ++++++++++++++++++++++----------------------
 multi_timer.h | 52 ++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 64 insertions(+), 33 deletions(-)

diff --git a/multi_timer.c b/multi_timer.c
index 3d49873..5924279 100755
--- a/multi_timer.c
+++ b/multi_timer.c
@@ -15,7 +15,9 @@ static uint32_t _timer_ticks = 0;
   * @brief  Initializes the timer struct handle.
   * @param  handle: the timer handle strcut.
   * @param  timeout_cb: timeout callback.
+  * @param  timeout: delay to start the timer.
   * @param  repeat: repeat interval time.
+  * @param  arg: the input argument for timeout_cb fucntion.
   * @retval None
   */
 void timer_init(struct Timer* handle, void (*timeout_cb)(void *arg), \
@@ -36,36 +38,40 @@ void timer_init(struct Timer* handle, void (*timeout_cb)(void *arg), \
 int timer_start(struct Timer* handle)
 {
     struct Timer* target = head_handle;
-    while(target)
-    {
-        if(target == handle)
+
+    while(target) {
+        if(target == handle) {
             return -1;  //already exist.
+        }            
         target = target->next;
     }
     handle->next = head_handle;
     head_handle  = handle;
+
     return 0;
 }
 
 /**
   * @brief  Stop the timer work, remove the handle off work list.
   * @param  handle: target handle strcut.
-  * @retval None
+  * @retval 0: succeed. -1: timer not exist.
   */
-void timer_stop(struct Timer* handle)
+int timer_stop(struct Timer* handle)
 {
     struct Timer** curr;
-    for(curr = &head_handle; *curr;)
-    {
+
+    for(curr = &head_handle; *curr;) {
         struct Timer* entry = *curr;
-        if(entry == handle)
-        {
+        if(entry == handle) {
             *curr = entry->next;
-            //			free(entry);
-        }
-        else
+            //free(entry);
+            return 0; // found specified timer
+        } else {
             curr = &entry->next;
+        }            
     }
+
+    return 0;
 }
 
 /**
@@ -76,16 +82,12 @@ void timer_stop(struct Timer* handle)
 void timer_loop(void)
 {
     struct Timer* target;
-    for(target = head_handle; target; target = target->next)
-    {
-        if(_timer_ticks >= target->timeout)
-        {
-            if(target->repeat == 0)
-            {
+
+    for(target = head_handle; target; target = target->next) {
+        if(_timer_ticks >= target->timeout) {
+            if(target->repeat == 0) {
                 timer_stop(target);
-            }
-            else
-            {
+            } else {
                 target->timeout = _timer_ticks + target->repeat;
             }
             target->timeout_cb(target->arg);
@@ -102,4 +104,3 @@ void timer_ticks(void)
 {
     _timer_ticks += CFG_TIMER_1_TICK_N_MS;
 }
-
diff --git a/multi_timer.h b/multi_timer.h
index 0f60453..dc9f0e8 100755
--- a/multi_timer.h
+++ b/multi_timer.h
@@ -6,8 +6,8 @@
 #ifndef _MULTI_TIMER_H_
 #define _MULTI_TIMER_H_
 
-#include "stdint.h"
-#include "stddef.h"
+#include <stdint.h>
+#include <stddef.h>
 
 /*
 It means 1 tick for 1ms. 
@@ -16,26 +16,56 @@ Your can configurate for your tick time such as 5ms/10ms and so on.
 #define CFG_TIMER_1_TICK_N_MS   1
 
 typedef struct Timer {
-    uint32_t        timeout;
-    uint32_t        repeat;
-    void *          arg; /* Input argument for timeout_cb function */
-    void            (*timeout_cb)(void *arg);
-    struct Timer*   next;
+    uint32_t        timeout;    /* Delay (xx ms) time to start tiemr */
+    uint32_t        repeat;     /* Timer interval expired time (xx ms) */
+    void *          arg;        /* Input argument for timeout_cb function */
+    void            (*timeout_cb)(void *arg); /* Timer expired callback function */
+    struct Timer*   next;       /* Pointer to next timer */
 } Timer;
 
 #ifdef __cplusplus  
 extern "C" {  
 #endif  
 
+/**
+  * @brief  Initializes the timer struct handle.
+  * @param  handle: the timer handle strcut.
+  * @param  timeout_cb: timeout callback.
+  * @param  timeout: delay to start the timer.
+  * @param  repeat: repeat interval time.
+  * @param  arg: the input argument for timeout_cb fucntion.
+  * @retval None
+  */
 void timer_init(struct Timer* handle, void(*timeout_cb)(void *arg), \
             uint32_t timeout, uint32_t repeat, void *arg);
+
+/**
+  * @brief  Start the timer work, add the handle into work list.
+  * @param  btn: target handle strcut.
+  * @retval 0: succeed. -1: already exist.
+  */
 int  timer_start(struct Timer* handle);
-void timer_stop(struct Timer* handle);
+
+/**
+  * @brief  Stop the timer work, remove the handle off work list.
+  * @param  handle: target handle strcut.
+  * @retval 0: succeed. -1: timer not exist.
+  */
+int timer_stop(struct Timer* handle);
+
+/**
+  * @brief  background ticks, timer repeat invoking interval nms.
+  * @param  None.
+  * @retval None.
+  */
 void timer_ticks(void);
-void timer_loop(void);
 
-// void timer_again(struct Timer* handle);
-// void timer_set_repeat(struct Timer* handle, uint32_t repeat);
+/**
+  * @brief  main loop.
+  * @param  None.
+  * @retval None
+  */
+void timer_loop(void);
 
 #ifdef __cplusplus
 }