Just a Theory

By David E. Wheeler

Posts about JavaDoc

JSDoc Doesn't Quite do the Trick for Me

After my request for JavaScript documentation standards, I investigated the one I found myself: JSDoc. I went ahead and used its syntax to document a JavaScript class I’d written, and it seemed to work pretty well. Initially, my main complaint was that their was no easy way to include arbitrary documentation. Everything has to be associated with a constructor, attribute, or method. Bleh.

But then I started documenting two purely functional JavaScript files I’d written. These just create functions in the Global scope for general use. And here’s where JSDoc started to really become a PITA. First, functions with the same names in the two files were declared to be pre-declared! They two files are part of the same project, but users will generally use one or the other, not both. But JSDoc has taken it upon itself to refuse to document functions that are in two different files in the same project. Surely that’s the JavaScript interpreter’s responsibility!

The next issue I ran into (after I commented out the code in JSDoc.pm that refused to document functions with the same names) was that it didn’t recognize one of the files as having documentation, because there was no constructor. Well duh! A purely functional implementation doesn’t have a constructor! It seems that Java’s bias for OO-only implementations has unduly influenced JSDoc, even though JavaScript applications often define no classes at all!

The clincher in my decision to ditch JSDoc, however, came when I realized that, for most projects, I won’t want the documentation in the same file as the code. While I generally prefer that they be in the same file, I will often have 4-10 times more documentation than actual code, and the bandwidth overhead seems unnecessary. JavaDoc and JSDoc of course require that any documentation be in the same files, since that’s where they parse method signatures and such.

So I think I’ll follow Chris Dolan’s advice from my original post and fall back on Good ‘ole POD. POD allows me to write as much or as little documentation as I like, with methods and functions documented in an order that makes sense to me, with headings even! I can write long descriptions, synopses, and even documentation completely unrelated to specifics of the interface. And all in a separate file, even!

This will do until someone formalizes a standard for JavaScript. Maybe it’ll be KwiD?

Looking for the comments? Try the old layout.

More about…

Is there a JavaScript Library Documentation Standard?

Is there a JavaScript documentation standard? I’ve been working on a test framework for JavaScript and I’d like to integrate documentation so that others can use it.

If there isn’t a documentation standard, I can see three possible options that I’d like to suggest:

Use XHTML.

Since JavaScript is mainly used for XHTML, it makes some sense to just use XHTML for its documentation. The downside to this is that there is currently no way to parse out the documentation, AFAIK. The format for putting the docs into comments would have to be standardized. I don’t really see that happening.

Use POD.

JavaScript is a dynamic language; it’d make some sense to use the documentation format of an existing dynamic language. And POD is a proven format. The downside, of course, is that there is not a parser for pulling POD out of a .js file. Same problem as for XHTML, essentially.

Use JavaDoc

Since the syntax of JavaScript is roughly based on JavaScript, and JavaScript supports the same comment syntax, one could simply use the JavaDoc format. The javadoc application probably couldn’t parse it out too well, since it parses the Java code (or byte code?) to automatically document method names, signatures, etc.

But a quick Googling yields JSDoc as a possible solution. The only downside to the JavaDoc/JSDoc solution is that it tends to allow authors to be too lazy. Since the application automatically documents the existence of functions and their signatures, often little else is documented. But that’s mainly a personal issue; I don’t have to be so lazy in my own documentation! I think I’ll give that a shot.

Meanwhile, if anyone knows of something better/more widely used, let me know!

"Learn about JSDoc (written in Perl!) on the project home
    page"

Looking for the comments? Try the old layout.