Cleanup some JSDocs related to observables

[pisv]

Mainly, this PR proposes to relax the constraint

Before the given observable can call this method again, is must call IObserver.endUpdate

in the JSDoc for the IObserver.beginUpdate method.

All existing observer implementations in VS Code are resilient to repeated calls of beginUpdate for the same observable, provided that each call is eventually accompanied with the corresponding endUpdate call. (All the implementations are based on using an update counter.)

Whereas the current implementation of ObservableValue does not satisfy this constraint when its set method is repeatedly called with the same transaction. (In that case, it will repeatedly call tx.updateObserver(observer, this), which will repeatedly call observer.beginUpdate(observable).)

[hediet]

Thanks! Good observation! Out of curiosity, what made you look into the observable implementation?

[pisv]

Out of curiosity, what made you look into the observable implementation?

I'd like to port the 3-way merge editor from VS Code to Eclipse Theia, and it is heavily based on the observable framework :)

By the way, I really appreciate the clean code you have written! Great job 👍