Documentation is ambiguous

[AmrSaber]

The documentation is not obvious, I mean I know what watchdog timer is and how it should work and all, but the API reference is not clear.

I can't understand what event gets called when, and what does each function do (feed function has the documentation that it feeds the dog!).

I don't even know how this maps to the watchdog timer standard where there is a reset (or a kick), that resets the timer, and a callback that gets invoked if time passes (timeout) and no reset was invoked.

If you could please make things more clear, I (and probably other people) would be grateful.

[aalku]

I think I got to understand it but not the text nor the example were clear enough, I had to read the internal code and test it.

First of all I didn't understand the very "main" verbs about the watchdog:

1. "Reset" means the watchdog "alarms". In a typical use case if the watchdog "resets" you would need to reset something because it was frozen or failing.
2. "Feed" means you delay the "reset" event. It means the system is working fine.
3. "Sleep" means you pause the need for "food". It will be activated again (I think) when the watchdog is "fed".

Then I needed to understand how they actually work in detail:

1. A new watchdog won't reset unless it's "feeded" for the first time. It's the first feed that starts the timer.
2. After a reset, if you need the timer to run again you need to "feed" the watchdog. Otherwise it's stopped.
3. The "food" object is modified internally in a way that will make different watchdogs interact with each other in a way you don't expect (they will copy the default timeout from one to another) so it's important that you create a new food object for each watchdog if you have several of them with different timeouts.

About that last point I think that's a mistake of design and should be corrected.