big update to observe, template_binding, polymer

pkg/observe/lib/src/bindable.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library observe.src.bindable;
+
+/// An object that can be data bound.
+// Normally this is used with 'package:template_binding'.
+// TODO(jmesserly): Node.bind polyfill calls this "observable"
+abstract class Bindable {
+  // TODO(jmesserly): since we have "value", should open be a void method?
+  // TODO(jmesserly): not sure how I feel about open taking a variable number
+  // of arguments, but it's the easiest way to make CompoundObserver work.
+
+  /// Initiates observation and returns initial value.

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

returns initial => returns the initial

[Jennifer Messerly, 2014/02/04 00:33:06]

Done.

+  /// The callback will be called with updated value. Some subtypes may also

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

with update => with the updated

[Jennifer Messerly, 2014/02/04 00:33:06]

Done.

+  /// provide old value as the second argument, or other information. Regardless

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

This was a bit confusing and I only understood what was happening when I read
the code of each subclass. It might help to rephrase this a bit, maybe include a
description both in the eyes of a binding-developer and a binding-user. For
example:

If you are implementing [Bindable], [open] should accept functions of 0, 1, 2, 3
args and even functions with optional args in between. If you are using
[Bindable] you can pass in as a callback any function that takes only positional
arguments up-to 3(?) args. 

(or maybe tell the binding-user that he needs to know what bindable he is
connecting to, and check its API?)

[Jennifer Messerly, 2014/02/04 00:33:06]

attemped to reword this, also added more precise docs to
PathObserver/CompoundObserver

+  /// it should support functuons that accept a single argument.

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

functiuons => functions

[Jennifer Messerly, 2014/02/04 00:33:06]

Done.

+  open(callback);
+
+  /// Stops future notification and references to the callback passed to [open].

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

notification -> notifications
not sure what it means to stop references? removes the reference to the callback
so it wont be leaked?

[Jennifer Messerly, 2014/02/04 00:33:06]

reworded

+  void close();
+
+  /// Gets the current value of the bindings.
+  get value;
+
+  /// This can be implemented for two-way bindings. By default does nothing.
+  /// Note: setting the value of a [Bindable] must not call the [callback] with
+  /// the new value. Essentially the pending change is discarded.

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

not sure what 'pending change' means here.

Also - why setting the value doesn't trigger an event? (feel free to tell me in
person if it's easier)

[Jennifer Messerly, 2014/02/04 00:33:06]

it's to avoid cycles in 2-way bindings, is my understanding. I don't have deep
understanding, I just wanted to document how the APIs should behave :)

FWIW, the JS version has an explicit `discardChanges()`, but it's always called
in practice after the value is set via `setValue(...)`. Also they use
`discardChanges()` to read the value, instead of a value getter. In Dart
setValue felt very unnatural, so I made it a getter/setter pair, and folded
discardChanges into it. It would be possible to pull discardChanges into a
separate method tho.

+  set value(newValue) {}
+}