A JSDoc Template to Output SDOCML Files

In one of my recent posts, I wrote about how to create a SDOCML file to extend Aptana (JavaScript IDE) content assist. This is part of my quest to find an IDE that can provide content assist as well as Eclipse’s Java IDE. But creating these files manually is just too cumbersome. What I needed was a way to auto generate these from my code base.

JSDoc To The Rescue

Jsdoc is a great tool if you are developing plugins or libraries that will be used by other people. It runs against your source code, picks up the jsdoc dockets (tokens that describe your functions and variables) and builds up documentation for it – normally in HTML format – essentially generating API documentation for your code. The output of the tool is controlled by a jsdoc template that can be defined on input and whom receives all of the information jsdoc was able to read from your source files.

I’m a big fan of documenting code. I personally think it helps in quickly understanding how to use a piece of code, and prevents wasted time in reading other people’s code just to try and figure out how to use it. JSDoc doclet can be seen all through out my code, thus creating a template that will output that documentation in the format that Aptana needs quickly became a necessity.

The Template

After searching the web for a template that would allow me to produce SDOCML formatted XML files, I found none. So I created my own. The template can be downloaded from github (here) and produces one single file – the SDOCML formatted file ready to be used with Aptana. It’s purpose is to output JavaScript Classes along with its instance and static methods.

Use it like any other JSDoc template, by using the –template input options and pointing to the folder that contains the template (the one with the publish.js file):

jsdoc --template ./jsdoc-sdocml-template/template ./src

There are a few things that this template alters in the output. These were needed in order for the file to be compliant with Aptana’s SDOCML definition. They are:

  • It outputs (currently) only Classes and Namespaces, along with their members
  • JSDoc Module names are stripped from the XML file due to unsupported characters. So something that may be annotated like this – module:widget/computers.Mac – will be output as: Mac
  • Some Type definitions are adjusted so that Aptana can recognize them

So does it work?

In a sense, for simple Classes, yes it does work. But Aptana seems to be very sensitive to the format used on type inference and to the content of the SDOCML files.

Example: Classes attached to namespaces (ie. Object) don’t seem to get recognized:

/** @namespace my */
var my = {};

 * A widget factory
 * @class my.Widget
my.Widget = function(){}

Also, Type inference is not consistent and as detailed in my prior post, Aptana is just too sensitive as to when it show content assist and when it does not. I had high hopes for this solution. The thought of being able to add good content assist to a JavaScript editor by simply dropping in a file is an awesome concept. It avoids depending on editor-dependent conventions that may not match the style of code you are working with.

Maybe I need to give up on Aptana!

What’s Next?

I’m not done yet.  In trying NetBeans IDE recently I found that not every editor has a “drop-in file” concept for augmenting content assist. It (and other IDEs/Editors) do however, have good support for reading and understanding the classic way of building a JavaScript Class:

function Widget() {}

Widget.prototype.getParam = function() {};

Widget.prototype.setParam = function(){};

We all know that in today’s OO JavaScript programing, you are always most likely going to have a Class Constructor instead of defining them the way detailed above. I realize now that what I need is for a JSDoc template that output JavaScript code. Yes, generate code from code. I need the output to simply provide a stub representation of the Classes and Namespaces using the standard “classic’ way of defining these.

So the stage is set for the next post on this topic.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s