tmr:start() does not restart started timer

[532910]

Expected behavior

https://nodemcu.readthedocs.io/en/master/modules/tmr/#tobjstart
says that tmr:start() restarts timer. It's not true:

Actual behavior

tmr:start() will restart timer (start it count from zero)

Test code

> t = tmr.create()
> t:register( 3000, tmr.ALARM_SEMI, function( t ) print( 'alarm' ) end)
> t:start()
> -- wait 2 seconds
> t:start()
> -- alarm message will be printed 3 seconds after the first t:start() call, not the second one as expected.

Workaround

t:stop()
t:start()

NodeMCU startup banner

NodeMCU 3.0.1.0, build type: integer
modules: file,gpio,net,node,rtctime,sntp,tmr,uart,wifi
build 2020-01-27 17:39 powered by Lua 5.1.4 on SDK 3.0.2(824dc80)

Hardware

ESP8266 wemos D1 (not mini)

[HHHartmann]

This seems to be an unclear documentation.
The second start in your example should return false as the timer is already running.
To achieve what you want you will need to stop the timer, and then start it again.

[532910]

So:

1. documentation should be corrected
2. tmr:restart() should be added

If there are no objections, I'm ready to PR. The question is: should it be two different pull requests or the one common will be fine?

[532910]

@marcelstoer, @TerryE can I make one single PR for the two points above or it should be two separate pull requests?

[TerryE]

@532910, I feel that both you and Gregor make valid points on this one We should think about valid use cases where this should apply, for example if the application is resetting an application watchdog. Do we insist on stopping the old timer first? Whatever, the code should not fail silently. It should return an error if the usage in incorrect.

Let's agree this first.

[HHHartmann]

I could also imagine to change tmr.stop to restart the timer if it is already running. But that might break existing code.

[532910]

you mean tmr.start, right?

[HHHartmann]

Yes. Must have been still half asleep

[fikin]

documentation should be corrected
tmr:restart() should be added
+1

imho clear api, clearer documentation and no visible backward compatibility risk.

[HHHartmann]

So should we go for tmr.restart() and better documentation of tmr.start() then?

[TerryE]

Or even one line Lua function to do the same stop / start, so I do think that adding an extra function to avoid this is a bit OTT.

Whatever, the code does need changing to return a correct error code.