The history of JSDoc
JSDoc in the wild
The term JSDoc by the way is a bit confusing. It refers both to the syntax and the program. The syntax has been relatively successful as well: “I know that a few of Google’s projects use JsDoc comments to extend their functionality. Closure Compiler is a good example of that, though it can be a pain when other projects start redefining the JsDoc syntax for their own purposes in ways that are incompatible with the original project. Of course there is no official standard for JsDoc comments, so I can’t blame them, but that is something I’d really like to see: an official JsDoc standard, I mean.”
“The idea of JSDoc has been picked up by many large projects over the years. However, my application was originally written in Perl and wasn’t very flexible, consequently it got rewritten by others a few times for internal use only. I don’t want to name any names because I personally think that, while perfectly legal to do that, it violates the open source spirit I intended the work to be used in.”
The Toolkit of JSDoc
Rhino runs on Java and was initially developed by Netscape. Rhino would have been a part of a larger project to port Netscape Navigator to the Java platform, but that never happened. Rhino is still being used and is maintained by the Mozilla Foundation.
How JSDoc works
JSDoc reads the code and the comments. The comments need to be formatted according to the JSDoc convention. It’s a notation that’s used in other tools like Google’s Closure as well and is similar to the JavaDoc convention.
“But for the rest of us JsDoc Toolkit provides a way to document your code in such a way that the tool never has to even see your code. In fact, you can even use JsDoc Toolkit in files with just comments, no code whatsoever! So in that sense there isn’t any code you can’t document with JsDoc Toolkit, as long as you don’t rely on the static code analysis features.”
The word “Toolkit” in the name “JSDoc Toolkit”, by the way refers to the template engine JSPlate. Michael: “I eventually went with the ‘Toolkit’ name mostly because I liked the sound of it, but also as a little nod to a favourite templating system of mine, Andy Wardley’s Perl Template Toolkit.”
JsDoc Toolkit Version 3
Right now Michael is in the middle of programming version 3 of JSDoc of which the first beta should be released somewhere this summer. “Basically there are a few feature requests from JsDoc Toolkit 2 that seem reasonable enough -things like documenting the same symbol more than once- which are utterly impossible due to the core architecture of the tool itself. All those feature requests are now on the table and I’ll try to include them in the new version.”
“One feature that will definitely be supported is the idea of overloaded functions. A typical example would be a function named ‘width()’ that returns the width when it is called with no arguments, but will set the width when called with a numeric argument.”
“This is fundamentally not possible to document in JsDoc Toolkit Version 2. And that really is the point of rewriting the tool for Version 3: it will include, in it’s core, all the lessons learned from the past several years of supporting JsDoc Toolkit. I believe it will provide a much more flexible foundation to build on.”
“Fast forward a few years and some important things have changed: namely, Norris Boyd has made accessing Rhino’s internal Abstract Syntax Tree much easier. In fact, it is now as easy to walk over your source code as it is to use, say, DOM nodes to walk over HTML. I’d be crazy not to take advantage of all that free power just sitting there waiting to be used!”
“So Version 3 will have none of my own parser left in it. This means I get to shed about 40% of the project’s code, which was dedicated to just that one task, and can now focus on the more important bits: parsing the doc comments.”
“It also means that, in theory, if Rhino can understand it, you’ll be able to get JsDoc Toolkit to understand it. Of course this is all taking time to get up to speed with, but I’ve decided to use build my tool on top of the new RingoJS framework and that’s made my life much easier, and the process much faster.”
The first beta of version 3 is estimated to be released in early summer.
One of the weak spots of the JSDoc project is that most of the time there’s only one active developer working on it. Although the tool is still alive and kicking, it naturally needs some nurturing to prevent it from getting stale. “To be honest it can feel like a real burden sometimes.” Michael admits. “It’s essentially just me these days, and I mostly can’t give the project all the time it deserves.” So developers are welcomed to join in the project: “I’m ready to sign them up! The fact is that I think of JSDoc as my baby. Not that I invented anything new or amazing, I most emphatically didn’t. But I’d lived with it long enough and I’d become associated with it, so I wanted to see it do well in life.”
A bit about Michael Mathews
It was hard to find a bit of information about New Yorker Michael Mathews. Although JSDoc has been around for almost 10 years and is downloaded a lot, he hasn’t been interviewed before. He has been asked many times for some assistance though. It can create funny situations: “I was doing some freelance work and the fellow sitting next to me asked if I’d ever heard anything about this ‘JSDoc’ stuff he was trying to use. I said I had heard of it and helped him sort it out. I had to eventually admit that I was the creator of the tool. He seemed a little surprised by that.”
Mathews started as a zookeeper, which he had done for a few years. But it wasn’t that much fun for him. “I basically cleaned up after lots of unusual animals.” When he wasn’t working, he played with his computer. “By the late nineties I was had my own homepage, complete with the large, requisite, ‘Under Construction’ message.” His work behind the computer payed off eventually: “in the fall of 1998 I was employed as a Web Developer for MTV Online, working in Times Square in New York City. It still seems amazing to me.