diff --git a/src/dom/form.js b/src/dom/form.js
index e165452..d8084e2 100644
--- a/src/dom/form.js
+++ b/src/dom/form.js
@@ -444,8 +444,37 @@ Form.Element.Serializers = {
/** section: DOM
* class Abstract.TimedObserver
+ *
+ * An abstract DOM element observer class, subclasses of which can be used to periodically
+ * check a value and trigger a callback when the value has changed.
+ *
+ * A `TimedObserver` object will try to check a value using the `getValue()`
+ * instance method which must be defined by the subclass. There are two out-of-the-box subclasses:
+ * [[Form.Observer]], which serializes a form and triggers when the result has changed; and
+ * [[Form.Element.Observer]], which triggers when the value of a given form field changes.
+ *
+ *
Creating Your Own TimedObserver Implementations
+ *
+ * It's easy to create your own `TimedObserver` implementations: Simply subclass `TimedObserver`
+ * and provide the `getValue()` method. For example, this is the complete source code for
+ * [[Form.Element.Observer]]:
+ *
+ * Form.Element.Observer = Class.create(Abstract.TimedObserver, {
+ * getValue: function() {
+ * return Form.Element.getValue(this.element);
+ * }
+ * });
**/
Abstract.TimedObserver = Class.create(PeriodicalExecuter, {
+ /**
+ * new Abstract.TimedObserver(element, frequency, callback)
+ * - element (String | Element): The DOM element to watch. Can be an element instance or an ID.
+ * - frequency (Number): The frequency, in seconds — e.g., 0.33 to check for changes every
+ * third of a second.
+ * - callback (Function): The callback to trigger when the value changes.
+ *
+ * Initializes an `Abstract.TimedObserver`; used by subclasses.
+ **/
initialize: function($super, element, frequency, callback) {
$super(callback, frequency);
this.element = $(element);
@@ -464,12 +493,21 @@ Abstract.TimedObserver = Class.create(PeriodicalExecuter, {
/** section: DOM
* class Form.Element.Observer < Abstract.TimedObserver
+ *
+ * An [[Abstract.TimedObserver]] subclass that watches for changes to a form field's value.
+ * This triggers the callback when the form field's value (according to
+ * [[Form.Element#getValue]]) changes. (Note that when the value actually changes can vary from
+ * browser to browser, particularly with `select` boxes.)
**/
Form.Element.Observer = Class.create(Abstract.TimedObserver, {
/**
* new Form.Element.Observer(element, frequency, callback)
+ * - element (String | Element): The form element to watch. Can be an element instance or an ID.
+ * - frequency (Number): The frequency, in seconds — e.g., 0.33 to check for changes every
+ * third of a second.
+ * - callback (Function): The callback to trigger when the value changes.
*
- * Creates a timed observer for a specific form control.
+ * Creates a Form.Element.Observer.
**/
getValue: function() {
return Form.Element.getValue(this.element);
@@ -478,13 +516,22 @@ Form.Element.Observer = Class.create(Abstract.TimedObserver, {
/** section: DOM
* class Form.Observer < Abstract.TimedObserver
+ *
+ * An [[Abstract.TimedObserver]] subclass that watches for changes to a form.
+ * The callback is triggered when the form changes — e.g., when any of its fields' values
+ * changes, when fields are added/removed, etc.; anything that affects the serialized
+ * form of the form (see [[Form#serialize]]).
**/
Form.Observer = Class.create(Abstract.TimedObserver, {
/**
* new Form.Observer(element, frequency, callback)
+ * - element (String | Element): The element of the form to watch. Can be an element
+ * instance or an ID.
+ * - frequency (Number): The frequency, in seconds -- e.g., 0.33 to check for changes every
+ * third of a second.
+ * - callback (Function): The callback to trigger when the form changes.
*
- * Creates a timed observer that triggers when any value changes within
- * the form.
+ * Creates a Form.Observer.
**/
getValue: function() {
return Form.serialize(this.element);