PDoc changes.

src/ajax/periodical_updater.js

@@ -34,7 +34,7 @@
  *    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>
+ *  <h4>Disabling and re-enabling a <code>PeriodicalUpdater</code></h4>
  *  
  *  You can hit the brakes on a running `PeriodicalUpdater` by calling
  *  [[Ajax.PeriodicalUpdater#stop]]. If you wish to re-enable it later, call
@@ -71,11 +71,24 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
     this.start();
   },
 
+  /**
+   *  Ajax.PeriodicalUpdater#start() -> undefined
+   *  
+   *  Starts the periodical updater (if it had previously been stopped with
+   *  [[Ajax.PeriodicalUpdater#stop]]).
+  **/
   start: function() {
     this.options.onComplete = this.updateComplete.bind(this);
     this.onTimerEvent();
   },
 
+  /**
+   *  Ajax.PeriodicalUpdater#stop() -> undefined
+   *  
+   *  Stops the periodical updater.
+   *  
+   *  Also calls the `onComplete` callback, if one has been defined.
+  **/
   stop: function() {
     this.updater.options.onComplete = undefined;
     clearTimeout(this.timer);

src/ajax/request.js

@@ -12,7 +12,7 @@
  *  property will automatically be passed to `eval`.
  *  
  *  In other words: you don't even need to provide a callback to leverage
- *  pure-JavaScript AJAX responses. This is the convention that drives Rails's
+ *  pure-JavaScript Ajax responses. This is the convention that drives Rails's
  *  RJS.
  *  
  *  The list of JavaScript-related MIME-types handled by Prototype is:
@@ -182,7 +182,7 @@ Ajax.Request = Class.create(Ajax.Base, {
   },
   
   /**
-   *  Ajax.Request.success() -> Boolean
+   *  Ajax.Request#success() -> Boolean
    *  
    *  Tests whether the request was successful.
   **/
@@ -240,7 +240,7 @@ Ajax.Request = Class.create(Ajax.Base, {
   },
   
   /**
-   *  Ajax.Request.getHeader(name) -> String | null
+   *  Ajax.Request#getHeader(name) -> String | null
    *  - name (String): The name of an HTTP header that may have been part of
    *    the response.
    *  

src/ajax/updater.js

@@ -9,9 +9,9 @@
  *  
  *  <h4>Example</h4>
  *  
- *    new Ajax.Updater('items', '/items', {
- *      parameters: { text: $F('text') }
- *    });
+ *      new Ajax.Updater('items', '/items', {
+ *        parameters: { text: $F('text') }
+ *      });
  *  
  *  This example will make a request to the URL `/items` (with the given
  *  parameters); it will then replace the contents of the element with the ID

src/dom/dom.js

@@ -1863,5 +1863,28 @@ Element.addMethods({
     }
     
     return value;
+  },
+  
+  /**
+   *  Element#clone(@element, deep) -> Element
+   *  - deep (Boolean): Whether to clone `element`'s descendants as well.
+   *  
+   *  Returns a duplicate of `element`.
+   *  
+   *  A wrapper around DOM Level 2 `Node#cloneNode`, `Element#clone` cleans up
+   *  any expando properties defined by Prototype.
+  **/
+  clone: function(element, deep) {
+    if (!(element = $(element))) return;
+    var clone = element.cloneNode(deep);
+    clone._prototypeUID = void 0;
+    if (deep) {
+      var descendants = Element.select(clone, '*'),
+          i = descendants.length;
+      while (i--) {
+        descendants[i]._prototypeUID = void 0;
+      }
+    }
+    return Element.extend(clone);
   }
 });

src/dom/event.js

@@ -2,6 +2,34 @@
   
   /** section: DOM
    * Event
+   *  
+   *  The namespace for Prototype's event system.
+   *  
+   *  <h4>Events: a fine mess</h4>
+   *  
+   *  Event management is one of the really sore spots of cross-browser
+   *  scripting.
+   *  
+   *  True, the prevalent issue is: everybody does it the W3C way, and MSIE
+   *  does it another way altogether. But there are quite a few subtler,
+   *  sneakier issues here and there waiting to bite your ankle — such as the
+   *  `keypress`/`keydown` issue with KHTML-based browsers (Konqueror and
+   *  Safari). Also, MSIE has a tendency to leak memory when it comes to
+   *  discarding event handlers.
+   *  
+   *  <h4>Prototype to the rescue</h4>
+   *  
+   *  Of course, Prototype smooths it over so well you’ll forget these
+   *  troubles even exist. Enter the `Event` namespace. It is replete with
+   *  methods that help to normalize the information reported by events across
+   *  browsers.
+   *  
+   *  `Event` also provides a standardized list of key codes you can use with
+   *  keyboard-related events.
+   *  
+   *  The functions you’re most likely to use a lot are [[Event.observe]],
+   *  [[Event#element]] and [[Event#stop]]. If your web app uses custom events,
+   *  you'll also get a lot of mileage out of [[Event.fire]].
   **/  
   var Event = {
     KEY_BACKSPACE: 8,
@@ -510,18 +538,21 @@
   });
 
   Element.addMethods({
-    /** alias of: Event.fire
+    /**
      *  Element#fire(@element, eventName[, memo[, bubble = true]]) -> Event
+     *  See [[Event.fire]].
     **/
     fire:          fire,
 
-    /** alias of: Event.observe
+    /**
      *  Element#observe(@element, eventName, handler) -> Element
+     *  See [[Event.observe]].
     **/
     observe:       observe,
     
-    /** alias of: Event.observe
+    /** 
      *  Element#stopObserving(element[, eventName[, handler]]) -> Element
+     *  See [[Event.stopObserving]].
     **/
     stopObserving: stopObserving
   });
@@ -535,16 +566,19 @@
   Object.extend(document, {
     /** 
      *  document.fire(eventName[, memo[, bubble = true]]) -> Event
+     *  See [[Event.fire]].
     **/
     fire:          fire.methodize(),
     
     /** 
      *  document.observe(eventName, handler) -> Element
+     *  See [[Event.observe]].
     **/
     observe:       observe.methodize(),
     
     /** 
      *  document.stopObserving([eventName[, handler]]) -> Element
+     *  See [[Event.stopObserving]].
     **/
     stopObserving: stopObserving.methodize(),
     

src/dom/form.js

@@ -1,5 +1,14 @@
 /** section: DOM
  * Form
+ *  
+ *  Utilities for dealing with forms in the DOM.
+ *  
+ *  `Form` is a namespace for all things form-related, packed with form
+ *  manipulation and serialization goodness. While it holds methods dealing
+ *  with forms as a whole, its submodule [[Form.Element]] deals with specific
+ *  form controls.
+ *  
+ *  Many of these methods are also available directly on `form` elements.
 **/
 
 var Form = {
@@ -197,6 +206,22 @@ Form.Methods = {
 
 /** section: DOM
  * Form.Element
+ *  
+ *  Utilities for dealing with form controls in the DOM.
+ *  
+ *  This is a collection of methods that assist in dealing with form controls.
+ *  They provide ways to focus, serialize, disable/enable or extract current
+ *  value from a specific control.
+ *  
+ *  Note that nearly all these methods are available directly on `input`,
+ *  `select`, and `textarea` elements. Therefore, these are equivalent:
+ *  
+ *      Form.Element.activate('myfield');
+ *      $('myfield').activate();
+ *  
+ *  Naturally, you should always prefer the shortest form suitable in a
+ *  situation. Most of these methods also return the element itself (as
+ *  indicated by the return type) for chainability.
 **/
 
 Form.Element = {

src/lang/array.js

@@ -1,4 +1,4 @@
-/** section: Language, alias of: Array.from, related to: Array
+/** section: Language, related to: Array
  *    $A(iterable) -> Array
  * 
  *  Accepts an array-like collection (anything with numeric indices) and returns 
@@ -168,7 +168,7 @@ Array.from = $A;
    *  Array#flatten() -> Array
    *  Returns a “flat” (one-dimensional) version of the array.
    *
-   *  Nested arrays are recursively injected “inline”. This can prove very
+   *  Nested arrays are recursively injected "inline." This can prove very
    *  useful when handling the results of a recursive collection algorithm,
    *  for instance.
   **/
@@ -243,8 +243,12 @@ Array.from = $A;
       return array.detect(function(value) { return item === value });
     }); 
   }
+  
+  /** alias of: Array#clone
+   *  Array#toArray() -> Array
+  **/
 
-  /** alias of: Array#toArray
+  /**
    *  Array#clone() -> Array
    *
    *  Returns a duplicate of the array, leaving the original array intact.

src/lang/class.js

@@ -2,6 +2,11 @@
 
 /** section: Language
  * Class
+ *  
+ *  Manages Prototype's class-based OOP system.
+ *  
+ *  Refer to Prototype's web site for a [tutorial on classes and
+ *  inheritance](http://prototypejs.org/learn/class-inheritance).
 **/
 var Class = (function() {
   /**

src/lang/enumerable.js

@@ -10,7 +10,7 @@
  *  
  *  Prototype mixes `Enumerable` into several classes. The most visible cases
  *  are [[Array]] and [[Hash]], but you’ll find it in less obvious spots as
- *  well, such as in [[ObjectRange]] and various DOM- or AJAX-related objects.
+ *  well, such as in [[ObjectRange]] and various DOM- or Ajax-related objects.
  *  
  *  <h4>The <code>context</code> parameter</h4>
  *  

src/lang/function.js

@@ -1,5 +1,7 @@
 /** section: Language
  * class Function
+ *  
+ *  Extensions to the built-in `Function` object.
 **/
 Object.extend(Function.prototype, (function() {
   var slice = Array.prototype.slice;

src/lang/range.js

@@ -1,9 +1,10 @@
 /** section: Language
  * class ObjectRange
  *  
- *  Ranges represent an interval of values. The value type just needs to be
- *  "compatible" — that is, to implement a `succ` method letting us step from
- *  one value to the next (its successor).
+ *  A succession of values.
+ *  
+ *  An `ObjectRange` can model a range of any value that implements a `succ`
+ *  method (which links that value to its "successor").
  *  
  *  Prototype provides such a method for [[Number]] and [[String]], but you
  *  are (of course) welcome to implement useful semantics in your own objects,