hoodwink.d enhanced


What Say We Help Prototype Explain Itself? #

by why in inspect

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;

    * 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.

said on 10 Jun 2005 at 15:01

How about nothing more than an RDoc parser. Should be quite easy to take the C R Doc parser and make it a JS R Doc parser.

said on 10 Jun 2005 at 15:49

Adding more languages to RDoc can only be good. It might widen the set of potential maintainers, for one thing.

said on 10 Jun 2005 at 16:05

Expanding the coverage RDoc seems like it could only be a good thing.

A quick hack is nice, but probably won’t have the staying power.

How to map from relatively neat Ruby concepts to the fast-and-loose prototype-based world of Javascript, though?

A lot of this stuff is convention rather than a feature of the language. So coming up with a logical organization for the generated RDoccery might be a bit tricky.

Of course any other JavaScript solution will be subject to the same problem.

said on 10 Jun 2005 at 16:06

Hmm, I did try a quick hack anyhow, although I got sick of working on it halfway through. Should I still post it?

said on 10 Jun 2005 at 16:09

I agree, RDoc already has a basic formatter in it, so you don’t really need to even use (red|blue)cloth ;)

said on 10 Jun 2005 at 22:17

Since discovering that RDoc also parses Fortran 95, I am beginning to see the light. Thankyou. As it turns out, I love my readers. They are a fragrant blend: quippy and contrarywise. But, seriously: FORTRAN 95 !

Comments are closed for this entry.