doc: Cleanup and normalize PDoc source

src/ajax.js

@@ -3,12 +3,12 @@
  *
  *  Prototype's APIs around the `XmlHttpRequest` object.
  *
- *  The Prototype framework enables you to deal with Ajax calls in a manner that is
- *  both easy and compatible with all modern browsers.
+ *  The Prototype framework enables you to deal with Ajax calls in a manner that
+ *  is both easy and compatible with all modern browsers.
  *
  *  Actual requests are made by creating instances of [[Ajax.Request]].
  *
- *  <h5>Request headers</h5>
+ *  ##### Request headers
  *
  *  The following headers are sent with all Ajax requests (and can be
  *  overridden with the `requestHeaders` option described below):
@@ -21,13 +21,13 @@
  *  * `Content-type` is automatically determined based on the `contentType`
  *    and `encoding` options.
  *
- *  <h5>Ajax options</h5>
+ *  ##### Ajax options
  *
  *  All Ajax classes share a common set of _options_ and _callbacks_.
  *  Callbacks are called at various points in the life-cycle of a request, and
  *  always feature the same list of arguments.
  *
- *  <h5>Common options</h5>
+ *  ##### Common options
  *
  *  * `asynchronous` ([[Boolean]]; default `true`): Determines whether
  *    `XMLHttpRequest` is used asynchronously or not. Synchronous usage is
@@ -64,7 +64,7 @@
  *    `true` otherwise): Sanitizes the contents of
  *    [[Ajax.Response#responseText]] before evaluating it.
  *
- *  <h5>Common callbacks</h5>
+ *  ##### Common callbacks
  *
  *  When used on individual instances, all callbacks (except `onException`) are
  *  invoked with two parameters: the [[Ajax.Response]] object and the result of

src/ajax/periodical_updater.js

@@ -4,9 +4,9 @@
  *  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
+ *  [[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.)
+ *  _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
@@ -16,10 +16,11 @@
  *  keeping track of the response text so it can (optionally) react to
  *  receiving the exact same response consecutively.
  *
- *  <h5>Additional options</h5>
+ *  ##### Additional options
  *
- *  `Ajax.PeriodicalUpdater` features all the common options and callbacks
- *  described in the [[Ajax section]] &mdash; _plus_ those added by `Ajax.Updater`.
+ *  [[Ajax.PeriodicalUpdater]] features all the common options and callbacks
+ *  described in the [[Ajax section]] &mdash; _plus_ those added by
+ *  [[Ajax.Updater]].
  *
  *  It also provides two new options:
  *
@@ -34,9 +35,9 @@
  *    is the same; when the result is different once again, `frequency` will
  *    revert to its original value.
  *
- *  <h5>Disabling and re-enabling a <code>PeriodicalUpdater</code></h5>
+ *  ##### Disabling and re-enabling a [[Ajax.PeriodicalUpdater]]
  *
- *  You can hit the brakes on a running `PeriodicalUpdater` by calling
+ *  You can hit the brakes on a running [[Ajax.PeriodicalUpdater]] by calling
  *  [[Ajax.PeriodicalUpdater#stop]]. If you wish to re-enable it later, call
  *  [[Ajax.PeriodicalUpdater#start]].
  *
@@ -55,7 +56,7 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
    *  - options (Object): Configuration for the request. See the
    *    [[Ajax section]] for more information.
    *
-   *  Creates a new `Ajax.PeriodicalUpdater`.
+   *  Creates a new [[Ajax.PeriodicalUpdater]].
    *  
    *  Periodically performs an AJAX request and updates a container's contents
    *  based on the response text. Offers a mechanism for "decay," which lets it   
@@ -71,7 +72,7 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
    *  
    *  ##### Additional options
    *  
-   *  `Ajax.PeriodicalUpdater` features all the common options and callbacks
+   *  [[Ajax.PeriodicalUpdater]] features all the common options and callbacks
    *  (see the [[Ajax section]] for more information), plus those added by
    *  [[Ajax.Updater]]. It also provides two new options that deal with the
    *  original period, and its decay rate (how Rocket Scientist does that make
@@ -111,7 +112,8 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
    *  </tbody>
    *  </table>
    *  
-   *  To better understand decay, here is a small sequence of calls from the following example:
+   *  To better understand decay, here is a small sequence of calls from the
+   *  following example:
    *  
    *      new Ajax.PeriodicalUpdater('items', '/items', {
    *        method: 'get', frequency: 3, decay: 2
@@ -188,17 +190,17 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
    *  </tbody>
    *  </table>
    *  
-   *  ##### Disabling and re-enabling a `PeriodicalUpdater`
+   *  ##### Disabling and re-enabling a [[Ajax.PeriodicalUpdater]]
    *  
-   *  You can pull the brake on a running `PeriodicalUpdater` by simply calling
-   *  its `stop` method. If you wish to re-enable it later, just call its `start`
-   *  method. Both take no argument.
+   *  You can pull the brake on a running [[Ajax.PeriodicalUpdater]] by simply
+   *  calling its `stop` method. If you wish to re-enable it later, just call
+   *  its `start` method. Both take no argument.
    *  
    *  ##### Beware!  Not a specialization!
    *  
-   *  `Ajax.PeriodicalUpdater` is not a specialization of [[Ajax.Updater]],
+   *  [[Ajax.PeriodicalUpdater]] is not a specialization of [[Ajax.Updater]],
    *  despite its name. When using it, do not expect to be able to use methods
-   *  normally provided by [[Ajax.Request]] and "inherited" by `Ajax.Updater`,
+   *  normally provided by [[Ajax.Request]] and "inherited" by [[Ajax.Updater]],
    *  such as `evalJSON` or `getHeader`. Also the `onComplete` callback is
    *  hijacked to be used for update management, so if you wish to be notified
    *  of every successful request, use `onSuccess` instead (beware: it will get

src/ajax/updater.js

@@ -4,10 +4,10 @@
  *  A class that performs an Ajax request and updates a container's contents
  *  with the contents of the response.
  *
- *  `Ajax.Updater` is a subclass of [[Ajax.Request]] built for a common
+ *  [[Ajax.Updater]] is a subclass of [[Ajax.Request]] built for a common
  *  use-case.
  *
- *  <h5>Example</h5>
+ *  ##### Example
  *
  *      new Ajax.Updater('items', '/items', {
  *        parameters: { text: $F('text') }
@@ -17,15 +17,15 @@
  *  parameters); it will then replace the contents of the element with the ID
  *  of `items` with whatever response it receives.
  *
- *  <h5>Callbacks</h5>
+ *  ##### Callbacks
  *
- *  `Ajax.Updater` supports all the callbacks listed in the [[Ajax section]].
+ *  [[Ajax.Updater]] supports all the callbacks listed in the [[Ajax section]].
  *  Note that the `onComplete` callback will be invoked **after** the element
  *  is updated.
  *
- *  <h5>Additional options</h5>
+ *  ##### Additional options
  *
- *  `Ajax.Updater` has some options of its own apart from the common options
+ *  [[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>`
@@ -34,18 +34,18 @@
  *    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 &mdash;
- *    `top`, `bottom`, `before`, or `after` &mdash; and _inserts_ the contents of the
- *    response in the manner described by [[Element#insert]].
+ *    `top`, `bottom`, `before`, or `after` &mdash; and _inserts_ the contents
+ *    of the response in the manner described by [[Element#insert]].
  *
- *  <h5>More About `evalScripts`</h5>
+ *  ##### More About `evalScripts`
  *
- *  If you use `evalScripts: true`, any _inline_ `<script>` block will be evaluated.
- *  This **does not** mean it will be evaluated in the global scope; it won't, and that
- *  has important ramifications for your `var` and `function` statements.  Also note
- *  that only inline `<script>` blocks are supported; external scripts are ignored.
- *  See [[String#evalScripts]] for the details.
+ *  If you use `evalScripts: true`, any _inline_ `<script>` block will be
+ *  evaluated. This **does not** mean it will be evaluated in the global scope;
+ *  it won't, and that has important ramifications for your `var` and `function`
+ *  statements.  Also note that only inline `<script>` blocks are supported;
+ *  external scripts are ignored. See [[String#evalScripts]] for the details.
  *
- *  <h5>Single container, or success/failure split?</h5>
+ *  ##### Single container, or success/failure split?
  *
  *  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