Documenting JavaScript with Doxygen

As you already know (Coherent UI announcement) we are developing a large C++ and JavaScript project. We have documentation for both programming languages. The main requirements for the documentation are:

• Application Programming Interface (API) references and general documentation such as quick start and detailed guides
• cross references between the API references and the guides
• accessible online and off line
• easy markup language

There are a lot documentation tools for each language - Doxygen, Sandcastle for C++, YUIDoc, JSDuck for JavaScript. Our project API is primary in C++, so we choose Doxygen. It is great for C++projects, but it doesn't support JavaScript. There are some scripts that solve this by converting JavaScript to C++ or Java. Unfortunately they do not support the modules pattern or have inconvenient syntax for the documentation. Our JavaScript API consists mostly of modules, so we wrote a simple doxygen filter for our documentation. A doxygen filter is a program that is invoked with the name of a file, and its output is used by doxygen to create the documentation for that file. To enable filters for specific file extension add

FILTER_PATTERNS =*.js=doxygen.js

view raw Doxyfile hosted with ❤ by GitHub

in the doxygen configuration file. Lets say we want to document the following module:

	/// @file Sync.js
	/// @namespace Sync
	/// Module for loading and storing data
	var Sync = {
	/// @function Sync.load
	/// Loads an resource
	/// @param {String} id the GUID of the resource
	/// @param {Function} success callback to be executed with the data on suceess
	/// @param {Function} error callback to be executed with error description in case of failure
	/// Loads an resource
	load : function (id, success, error) {
	},
	/// @function Sync.store
	/// Store an resource
	/// @param {String} id the GUID of the resource
	/// @param {Object} data the resource
	/// @param {Function} success callback to be executed when the store operation has completed successfully
	/// @param {Function} error callback to be executed with error description in case of failure
	/// Store an resource
	store : function (id, data, success, error) {
	},
	};

view raw Sync.js hosted with ❤ by GitHub

The filtered output looks like:

	/// @file Sync.js
	/// @namespace Sync
	/// Module for loading and storing data
	namespace Sync {
	/// Loads an resource
	/// @param id the GUID of the resource
	/// @param success callback to be executed with the data on suceess
	/// @param error callback to be executed with error description in case of failure
	/// Loads an resource
	undefined load(String id, Function success, Function error);
	}
	namespace Sync {
	/// Store an resource
	/// @param id the GUID of the resource
	/// @param data the resource
	/// @param success callback to be executed when the store operation has completed successfully
	/// @param error callback to be executed with error description in case of failure
	/// Store an resource
	undefined store(String id, Object data, Function success, Function error);
	}

view raw Sync.js.cpp hosted with ❤ by GitHub

A nice surprise is that when you want to link to Sync.load you can use `Sync.load`. The only annoying C++ artifacts in the JavaScript documentation are the "Sync namespace" and using "::" as resolution operator, but they can be fixed by a simple find / replace script. The doxygen.js filter is available at https://gist.github.com/3767879.