Kajabity.com

In this article I’ll tell you how I integrated JsDoc into the Wiki Text project to publish JavaDoc style documentation and at the same time solved the strange problem of a missing Outline view in Eclipse IDE.

The Problem

While I was developing the Wiki Text jQuery plugin I had a couple of problems I wanted to solve.

The first was that I became aware the Outline view in the Eclipse IDE I was using for development was empty.  I didn’t notice at first – it was my code and I could find my way around it – but as the code got longer and more complex it became a bit of a pain jumping around to each of the functions.

I suspect that part of the problem was that, following best advice on the development of jQuery plugins, I had wrapped the whole definition in an anonymous function declaration:

(function( jQuery )
{
	jQuery.wikiText = function( text )
	{
		var banana = 3;

		apple = 4;

		//...
	};

	jQuery.fn.wikiText = function( text )
	{
		return this.html( jQuery.wikiText( text ) );
	};
})( jQuery );

The second problem came when I wanted to publish documentation on the web – I am quite familiar with JavaDoc and vaguely remember seeing something similar done with JavaScript.  How hard could it be?

The answer, it seems, is Very Hard!  Not only is JavaScript a much more fluid language than Java – a variable can be a function can be a class can be an instance – but also (probably as a result of that)there are no standard products for generating documentation from it.  And, correspondingly, there doesn’t seem to be a well defined standard for marking up the code.

First Attempts

After a little hunting around, I settled on JsDoc and tried it out on a Windows command line.

The output was a tad disappointing – nothing but a couple of very empty web pages.  Not much like JavaDoc which would at least have listed the classes and methods even if there were no comments.  So I tried adding JavaDoc style comments – still nothing.

I hunted around the Internet for some useable examples and, bit by bit, worked out how to get it to work the way I wanted.  The rest of this article describes what I ended up with.  You can see the results at http://www.kajabity.com/jquery-wikitext/jsdoc/index.html.

Adding JsDoc Mark-up

I found a small number of examples and the first thing I noticed when I opened up one of them in the Eclipse IDE is that there was a full Outline view at the side of it.

After some experimentation and I found that the following minimum additions to my test script worked:

(function( jQuery )
{
	/**
	 * @memberOf jQuery
	 */
	jQuery.wikiText = function( text )
	{
		var banana = 3;

		apple = 4;

		//...
	};

	/**
	 * @memberOf jQuery.fn
	 */
	jQuery.fn.wikiText = function( text )
	{
		return this.html( jQuery.wikiText( text ) );
	};
})( jQuery );

This is illustrated in the following simplified screen shot:

Of course this may be down to the specific details of the Eclipse JavaScript plugin and may be different in other versions or configurations.

Once I realised this was the correct approach I added much more documentation to the JavaScript – this can be seen if you download the Wiki Text plugin for jQuery and look at the source.

There is also a Tag Reference available listing a whole host of (slightly mystifying) tags you can add.  There is clearly something dark and twisted about JavaScript, if you ask me…

How To Generate Documentation with JsDoc Toolkit

Starting at the beginning, I downloaded version 2.4.0 of the JsDoc Toolkit.  There were warnings about moving to version 3 on the download page – but this version works fine for me.

For the purposes of this blog post I have created a new directory, Test-JsDoc.  In this I created a subdirectory, script, in which I put a sample JavaScript file, test.js, containing the above sample code.

I have unzipped the downloaded toolkit and put the jsdoc-toolkit directory in the Test-JsDoc directory as well.

	Test-JsDoc
	  |
	  +-script
	  |
	  +-jsdoc-toolkit

In the jsdoc-toolkit directory is a README.txt file containing some useful instructions (also see Command Options).  Reading it I tried the following command:

java -jar jsdoc-toolkit\jsrun.jar jsdoc-toolkit\app\run.js -a -t=jsdoc-toolkit\templates\jsdoc script\test.js

Running the command the first time caused the following warnings:

>> WARNING: Trying to document wikiText as a member of undocumented symbol jQuery.
>> WARNING: Trying to document wikiText as a member of undocumented symbol jQuery.fn.

The documentation was generated in an output directory, out/jsdoc, under the jsdoc-toolkit directory and included virtually nothing of any use.

So, I modified the command to specify an output directory and added definitions for jQuery and jQuery.fn (and other documentation) as follows:

/**
 * @fileOverview Kajabity Wiki Text Plugin for jQuery
 * @author Simon J. Williams
 * @version: 0.3
 */
(function( jQuery )
{
	/**
	 * jQuery definition to anchor JsDoc comments.
	 *  
	 * @see http://jquery.com/
	 * @name jQuery
	 * @class jQuery Library
	 */

	/**
	 * jQuery Utility Function to convert Wiki formatted text to HTML.
	 * 
	 * @namespace Kajabity Wiki Text
	 * @function
	 * @param {string} text the Wiki text to be converted to HTML.
	 * @return {string} HTML formatted text.
	 * @memberOf jQuery
	 */
	jQuery.wikiText = function( text )
	{
		var html = '';

		//...
	};

	/**
	 * jQuery 'fn' definition to anchor JsDoc comments.
	 *  
	 * 
	 * @see http://jquery.com/
	 * @name fn
	 * @class jQuery Library
	 * @memberOf jQuery
	 */

	/**
	 * A jQuery Wrapper Function to append Wiki formatted text to a DOM object
	 * converted to HTML.
	 * 
	 * @class Wiki Text Wrapper
	 * @param {string} text text with Wiki mark-up.
	 * @return {jQuery} chainable jQuery class
	 * @memberOf jQuery.fn
	 */
	jQuery.fn.wikiText = function( text )
	{
		return this.html( jQuery.wikiText( text ) );
	};
})( jQuery );

This is the command:

java -jar jsdoc-toolkit\jsrun.jar jsdoc-toolkit\app\run.js -a -t=jsdoc-toolkit\templates\jsdoc –d=target\jsdoc script\test.js

And so the JsDoc output is generated – you can view your results by opening the index.html file in the specified output directory (target\jsdoc\index.html in this example).

In my next post I’ll explain how I use Apache Ant to automate the process.