micmath/jsdoc — pull request #87 by jannon (2012-02-25 08:29:25+00:00)
Title: Flexible parse

Preamble
--------------
(You can skip to the "Solution section" if you're pressed for time)
JavaScript is an extremely flexible language and people use it in many different and sometimes crazy ways. JSDoc3 does a great job of handling most of the common things people will do, but as JavaScript use increases, especially with its rise server-side, there will likely be increasingly different things people do with it.

The ability to create "virtual" doclets using the ```@name``` tag means folks can do just about anything, but let's face it, no one likes to do documentation and that takes more effort and it'd be nice if things were more automatic. Of course, it's not really feasible for JSDoc3 to add logic to handle every different thing people might do.

It would be great if plugin creators were given more power to handle different things, so folks interested in documenting certain types of things can create plugins that make it easy for other users and more people use JSDoc3 and we all move toward a more well-documented future.

The Problem
-------------------
My primary impetus for getting involved was a desire to document a big set of jQuery UI widgets. The jQuery UI widget framework, however, uses a class factory so to create a mywidget plugin, you might do something like:

$.widget("ui.mywidget", {});

Unfortunately, things weren't really set up to document that easily. I didn't want to have to write all the ```@name``` and ```@memberof``` tags to get things working right. Besides, the jQuery UI widget framework is fairly structured. There's the factory function that takes the class name and prototype, which contains an "options" object and some methods. It'd be a waste not to just have all of that documented automatically. But I needed to be able to do more with the parser.

The Solution
------------------
This branch contains three main changes that add enough flexibility to JSDoc3 that should allow anyone to get what they want out of it. The default behavior is unchanged and all tests pass.

### 1. Plugins can define tags

By exporting a 'defineTags' function which takes a dictionary, plugins can add tags to the standard ones

### 2. Plugins can define nodeVisitors

By exporting a 'nodeVisitor' object with a 'visitNode' function, plugins can now get direct access to the parse tree. When parser is visiting nodes, it does whatever it does with the node. Then it gives all attached plugin node visitors a chance to process the node, passing them any meta data it may have created. The node visitors can modify that data, or create data for a node that the main parser doesn't handle (like function calls). After the visitors have processed the node, an event is fired (usually 'symbolFound', but could conceivably be something else) and the regular parsing process ensues (listeners to the parser events are run). I guess change 2.5 is that plugins now export their event handlers in an object named 'handlers'

### 3. New Rhino jar

After initially trying to bend JSDoc3 to my will and subsequently realizing that that one big annoying problem was that Rhino wasn't attaching jsdoc comments to function calls, I took a break and moved on to working on my template and instrumenting a proof of concept widget with all the tags needed to make it work. Sure enough, though, I realized I didn't want to do that for all my widgets so I decided to fork the Rhino source yesterday and see what was what. Turns out it was just a 3-line change to the parser. If you're interested, you can take a look at that here: https://github.com/jannon/rhino

So that's that. I've got a plugin/template that makes use of everything to churn out some sweet docs for jQuery UI widgets, but It'll probably be a few days before I can get it up on github for folks to see