Linkerkind is once again swarming around the Ajax+Rails article just up today, but are you aware of how painfully vacant the documentation is for the underlying JavaScript library? From Prototype’s README:

Prototype is embarrassingly lacking in documentation. (The source code should be fairly easy to comprehend; I’m committed to using a clean style with meaningful identifiers. But I know that only goes so far.)

Much of the problem is that there is no easy way to document it from within the source code itself. I’ve tried JSDoc and a Perl script included with JsUnit; neither groks Prototype’s hash-style class definitions or inheritance scheme. Making them work would require major changes, and I don’t have the time for that right now.

Admittedly, Prototype’s syntax is excellently deviant from the norm. So, here’s what I propose. What about a little Ruby script to do the job? No need to fully parse the JS, just some basic Regexps. RDoc frames and templates need not apply.

Given this script, what can we do? How would you add documentation and what exactly would you parse? RedCloth/BlueCloth could save some time here.

  /* 
   * The Effect.Fade object vanishes an element, reducing its
   * opacity until it is invisible, then hiding the element from
   * display.
   * 
   *   onclick="new Effect.Appear('appear')" 
   */
 Effect.Fade = Class.create();
 Effect.Fade.prototype = {
   /* 
    * Returns a new Effect.Fade element, capable of producing
    * a fade on +element+.  (List possible options below.)
    */
   initialize: function(element) {
     this.element = $(element);
     this.start  = 100;
     this.finish = 0;
     this.current = this.start;
     this.fade();
   },

   /*
    * Actually activates the fade effect.
    */
   fade: function() {
     if (this.isFinished()) { this.element.style.display = 'none'; return; }
     if (this.timer) clearTimeout(this.timer);
     this.setOpacity(this.element, this.current);
     this.current -= 10;
     this.timer = setTimeout(this.fade.bind(this), 50);
   }, // ... and so on...

If you get partway and are tired of working on it, post a link to your halfway script and we’ll all take a stab.