Documentin' Ain't Easy

Creating a documentation system for Axiom Stack has been a unique challenge and I wanted to elaborate a bit on what we've come up with to do the job. 

Most widely used languages have good code-level documentation tools already: RDoc for Ruby, Javadoc for Java, etc.  You comment your code according to the coventions of the tool and the tool in turn takes them and spits out some nicely formatted, human-readable documentation. 

Our challenge: not everything in the Axiom Javascript environment is implemented in Javascript!  Axiom Stack itself is written in Java, while applications are written in Javascript.  The JS API available to your application code comes from two sources:

- Pure Java objects, wrapped up and exposed to the scripting layer via Rhino.  This is stuff like theAxiomObjectprototype and theappobject.

- Modules and libraries written in Javascript.  We include a number of utility libraries (like theftplibrary) and enhancements to existing JS prototypes like Array and String in this fashion.

So, we couldn't simply run the language-appropriate tool over all our code and be done with it.  Here's how we did it:

First, we created a class that used Sun'sDoclet APIto run over all our Java classes.  Any classes marked as exposed to the scripting layer are transformed into stub Javascript. This code doesn't do anything, but serves as an empty frame forjsdocto parse, and is thrown away after the build has completed. Quick example:

/** 
 * Grates cheese of your choice.
 * @jsconstructor
 */
public class CheeseGrater(){
 	/**
	 * @param {String} cheeseType Type of cheese.
	 */
   	public CheeseGrater(String cheeseType){
		    // ...
	}

	/**
	 * Grate up some cheese!
	 */
	public GratedCheese grate(){
		// ...
  	}			
}

Becomes:

/**
  * Grates cheese of your choice
  * @param {String} cheeseType Type of cheese.
  * @constructor
  */
function CheeseGrater(/**String*/ cheeseType){}

/**
  * Grate up some cheese!
  * @returns {GratedCheese}
  */	  
CheeseGrater.prototype.grate = function(){}

Then, we run jsdoc over both the Java-generated stub code and the real Javascript in our libraries and presto! Usable documentation.