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 in the doxygen configuration file. Lets say we want to document the following module:
The filtered output looks like:
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.