Utility problem with setWatch

I'm experiencing a usability problem with setWatch, wherein the documented behavior matches reality precisely, but it's not useful to me (I dare say not useful to anyone). I'm exploring possibilities for adjustments toward more practical utility. Scenario:

1. setWatch() with edge: 'rising' or 'falling'
   
2. in the event handler, print event.time and event.lastTime
   
3. compare each event's output to the output from the prior event
   
   

The result is that each event's 'lastTime' is mismatched with the 'time' of the prior event. With edge: 'both' (default), that's not the case, and the documentation corroborates this evidence; lastTime is NOT the time of the prior triggered event; it's the time of the last-state-change on the pin.

Perhaps it's only my lack of imagination, but I don't see how the time-of-last-state-change is useful to any client code. Time-of-last-event is IMO the only thing that could possibly be sensical from a "serve the client" point of view. A client who wants time-since-state-change can use edge:'both'.

Can we look for a way to fix this, to produce more usability for developers? It could be approached in any number of ways. I'll suggest a few here:

• change lastTime to be time-of-last-triggered-event. Not back-compatible.

• Add lastEventTime as time-of-last-triggered-event. Heavier, but back-compatible.

• Add lastEvent as a reference to the prior-triggered event; client code consults event.lastEvent.time instead of event.lastTime. Increases memory usage by one event per setWatch, but lightens the event structure (especially if lastTime becomes deprecated and then is removed)

I have not tested with noisy inputs, with or without debouncing, being a little bit busy, and a little bit afraid of the result :). Perhaps the debouncing logic holds the key for explaining the current behavior, but I'd be glad to help work out expectations and maybe even some code for it.

@all and @Gordon - your thoughts?

R