Adblock Plus and (a little) more

Generating JavaScript documentation · 2008-10-21 10:05 by Wladimir Palant

After years of neglecting code documentation I finally came around and added JSDoc comments to much of the Adblock Plus core. The next problem now — what tool should I use to extract these comments and generate documentation? Problem is, none of the off-the-shelf tools know JavaScript 1.8.

First there is the original JSDoc tool. It is written in Perl and uses regular expressions to “parse” JavaScript (urgh). I tried tweaking it a little but these regular expressions are already beyond maintainability and teaching them new tricks is almost impossible.

Then I discovered JSDoc Toolkit which looked very promising. It is written in JavaScript (running on Rhino), implements a real parser and supports plugins. Major disadvantage is that it doesn’t detect inheritance patterns automatically, adding that functionality via plugins wasn’t a problem however. In fact, it didn’t take me long to create a few patches (improve error messages, provide plugins with more information, support let keyword, support getters/setters, support expression closures, support E4X, show class hierarchy in generated pages). Making it run in xpcshell to improve performance shouldn’t be hard either. Problem is, even after three months my patches are still sitting there, no reaction whatsoever. Not sure whether the project is still under development, but I have very little interest in maintaining a fork.

So, are there any other options?

Tags: adblock plus mozilla

Comment [2]

1. kfleong · 2008-10-21 13:12 · #

   Doxygen?

   http://www.stack.nl/~dimitri/doxygen/index.html

   Reply from Wladimir Palant:

   Searching “Doxygen JavaScript” turned up: “For those working with JavaScript it may be good to know that Jörg Schaible has written a perl script to let doxygen deal with it”. And from the documentation of that script: “The generation is done using a Perl script generating Pseudo C++ code with the comments that is processed afterwards with DoxyGen”. That doesn’t sound very encouraging, already the typing should turn into a mess.

2. Andrew Sutherland · 2008-10-22 06:16 · #

   Nice patches to have! I had settled on using jsdoc-toolkit in the interim to provide the documentation for gloda (the global database for thunderbird). My mods have mainly been limited to improving the templating for another template to work well with gloda…

   jsdoc-toolkit hg tree: http://hg.mozilla.org/users/bugmail_asutherland.org/jsdoc-toolkit-visbrero/
   output produced: http://clicky.visophyte.org/momo/docs/gloda/outline/

   During my survey of the available tools, it had seemed like jsdoc-toolkit was going to be subject to another rewrite from scratch, but still seemed like the best available option right now…

Commenting is closed for this article.