From 4453e62fd5cdde675001ec0861f0f543accf384e Mon Sep 17 00:00:00 2001
From: Andrew Dupont <prototype@andrewdupont.net>
Date: Sat, 7 Mar 2009 20:01:22 -0600
Subject: [PATCH] Add the last of the documentation for the Ajax section.

---
 src/ajax/periodical_updater.js | 58 +++++++++++++++++++++
 src/ajax/updater.js            | 94 ++++++++++++++++++++++++++++++++--
 2 files changed, 147 insertions(+), 5 deletions(-)

diff --git a/src/ajax/periodical_updater.js b/src/ajax/periodical_updater.js
index 83ea294..03fa516 100644
--- a/src/ajax/periodical_updater.js
+++ b/src/ajax/periodical_updater.js
@@ -1,4 +1,62 @@
+/** section: Ajax
+ *  class Ajax.PeriodicalUpdater
+ *  
+ *  Periodically performs an Ajax request and updates a container’s contents
+ *  based on the response text.
+ *  
+ *  `Ajax.PeriodicalUpdater` behaves like [[Ajax.Updater]], but performs the
+ *  update at a prescribed interval, rather than only once. (Note that it is
+ *  _not_ a subclass of `Ajax.Updater`; it's a wrapper around it.)
+ *  
+ *  This class addresses the common need of periodical update, as required by
+ *  all sorts of “polling” mechanisms (e.g., an online chatroom or an online
+ *  mail client).
+ *  
+ *  The basic idea is to run a regular [[Ajax.Updater]] at regular intervals,
+ *  keeping track of the response text so it can (optionally) react to
+ *  receiving the exact same response consecutively.
+ *  
+ *  <h4>Additional options</h4>
+ *  
+ *  `Ajax.PeriodicalUpdater` features all the common options and callbacks
+ *  described in the [[Ajax section]] — _plus_ those added by `Ajax.Updater`.
+ *  
+ *  It also provides two new options:
+ *  
+ *  * `frequency` ([[Number]]; default is `2`): How long, in seconds, to wait
+ *    between the end of one request and the beginning of the next.
+ *  * `decay` ([[Number]]; default is `1`): The rate at which the `frequency`
+ *    grows when the response received is _exactly_ the same as the previous.
+ *    The default of `1` means `frequency` will never grow; override the
+ *    default if a stale response implies it's worthwhile to poll less often.
+ *    If `decay` is set to `2`, for instance, `frequency` will double
+ *    (2 seconds, 4 seconds, 8 seconds...) each consecutive time the result
+ *    is the same; when the result is different once again, `frequency` will
+ *    revert to its original value.
+ *  
+ *  <h4>Disabling and re-enabling a `PeriodicalUpdater`</h4>
+ *  
+ *  You can hit the brakes on a running `PeriodicalUpdater` by calling
+ *  [[Ajax.PeriodicalUpdater#stop]]. If you wish to re-enable it later, call
+ *  [[Ajax.PeriodicalUpdater#start]].
+ *  
+**/
+
 Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
+  /**
+   *  new Ajax.PeriodicalUpdater(container, url[, options])
+   *  - container (String | Element): The DOM element whose contents to update
+   *    as a result of the Ajax request. Can be a DOM node or a string that
+   *    identifies a node's ID.
+   *  - url (String): The URL to fetch. When the _same-origin_ policy is in
+   *    effect (as it is in most cases), `url` **must** be a relative URL or an
+   *    absolute URL that starts with a slash (i.e., it must not begin with
+   *    `http`).
+   *  - options (Object): Configuration for the request. See the
+   *    [[Ajax section]] for more information.
+   *  
+   *  Creates a new `Ajax.PeriodicalUpdater`.
+  **/
   initialize: function($super, container, url, options) {
     $super(options);
     this.onComplete = this.options.onComplete;
diff --git a/src/ajax/updater.js b/src/ajax/updater.js
index e1efa98..036dbe8 100644
--- a/src/ajax/updater.js
+++ b/src/ajax/updater.js
@@ -17,16 +17,100 @@
  *  parameters); it will then replace the contents of the element with the ID
  *  of `items` with whatever response it receives.
  *  
+ *  <h4>Callbacks</h4>
  *  
+ *  `Ajax.Updater` supports all the callbacks listed in the [[Ajax section]].
+ *  Note that the `onComplete` callback will be invoked **after** the element
+ *  is updated.
+ *  
+ *  <h4>Additional options</h4>
+ *  
+ *  `Ajax.Updater` has some options of its own apart from the common options
+ *  described in the [[Ajax section]]:
+ *  
+ *  * `evalScripts` ([[Boolean]]; defaults to `false`): Whether `<script>`
+ *    elements in the response text should be evaluated.
+ *  * `insertion` ([[String]]): By default, `Element.update` is used, meaning
+ *    the contents of the response will replace the entire contents of the
+ *    container. You may _instead_ insert the response text without disrupting
+ *    existing contents. The `insertion` option takes one of four strings —
+ *    `top`, `bottom`, `before`, or `after` — and _inserts_ the contents of the
+ *    response in the manner described by [[Element#insert]].
+ *  
+ *  <h4>About `evalScripts` and defining functions</h4>
+ *  
+ *  If you use `evalScripts: true`, any `<script>` block will be evaluated.
+ *  This **does not** mean it will be evaluated in the global scope. In other
+ *  words:
+ *  
+ *  * The evaluation scope will be that of Prototype's internal processing
+ *    function. Anything in your script declared with the `var` keyword will be
+ *    discarded momentarily after evaluation, and will be invisible to any
+ *    other scope.
+ *  * If any `<script>` blocks inside Ajax responses _define functions_, they
+ *    will need to be assigned to properties of the `window` object — _not_
+ *    declared with the `function` keyword.
+ *  
+ *  For example, this won't work:
+ *  
+ *      // This kind of script won't work if processed by Ajax.Updater:
+ *      function coolFunc() {
+ *        // Amazing stuff!
+ *      }
+ *  
+ *  Instead, use the following syntax:
+ *  
+ *      // This kind of script WILL work if processed by Ajax.Updater:
+ *      coolFunc = function() {
+ *        // Amazing stuff!
+ *      }
+ *  
+ *  <h4>Single container, or success/failure split?</h4>
+ *  
+ *  The examples above all assume you’re going to update the same container
+ *  whether your request succeeds or fails. Instead, you may want to update
+ *  _only_ for successful requests, or update a _different container_ on failed
+ *  requests.
+ *  
+ *  To achieve this, you can pass an object instead of a DOM element for the
+ *  `container` parameter. This object _must_ have a `success` property whose
+ *  value identifies the container to be updated on successful requests.
+ *  
+ *  If you also provide it with a `failure` property, its value will be used as
+ *  the container for failed requests.
+ *  
+ *  In the following code, only successful requests get an update:
+ *  
+ *      new Ajax.Updater({ success: 'items' }, '/items', {
+ *        parameters: { text: $F('text') },
+ *        insertion: 'bottom'
+ *      });
+ *  
+ *  This next example assumes failed requests will deliver an error message as
+ *  response text — one that should be shown to the user in another area:
+ *  
+ *      new Ajax.Updater({ success: 'items', failure: 'notice' }, '/items', 
+ *        parameters: { text: $F('text') },
+ *        insertion: 'bottom'
+ *      });
  *  
 **/
 
-
-
-
-
-
 Ajax.Updater = Class.create(Ajax.Request, {
+  /**
+   *  new Ajax.Updater(container, url[, options])
+   *  - container (String | Element): The DOM element whose contents to update
+   *    as a result of the Ajax request. Can be a DOM node or a string that
+   *    identifies a node's ID.
+   *  - url (String): The URL to fetch. When the _same-origin_ policy is in
+   *    effect (as it is in most cases), `url` **must** be a relative URL or an
+   *    absolute URL that starts with a slash (i.e., it must not begin with
+   *    `http`).
+   *  - options (Object): Configuration for the request. See the
+   *    [[Ajax section]] for more information.
+   *  
+   *  Creates a new `Ajax.Updater`.
+  **/
   initialize: function($super, container, url, options) {
     this.container = {
       success: (container.success || container),