This post will most probably be no much fun to read - much like the researching of the topic was quite ... tedious. The question is how to set up a documentation of the Javascript API. There are certain requirements for such a setup:

• the doc should be maintained while coding and you should be able to use the same tools (i.e. IDE) for that
• the doc tool should have some basic knowledge of software and should therefore be able to automatically create cross links
• however close the act of documenting is to the act of source code production: the result in the end should be a shiny HTML document that is linked to the iLand wiki

The C++ source code documentation of iLand uses Doxygen, which is a very nice tool and tailored explicitely to C++ as the language. So my first guess was to try to somehow use the documentation of the C++ source code that is attached to the objects/functions related to the scripting engine. While that sounds straightforward, it has some problems: On the one hand, the syntax of C++ and Javascript is different (e.g., there is no void in JS), and, more important, the documentation targets the wrong audience: if you want to use the Javascript function, you'd probably not very interested in the details of marshaling data types between Javascript and C++. The alternative is to set up a specific "Javascript API documentation" that targets script hackers and deals with Javascript syntax. After some failings I stumbled upon a perl script for Javascript to Doxygen conversion. This script creates from Javascript a "kind" of C++ code which would not compile but can be processed by Doxygen. After a couple of minor difficulties (e.g. how to execute perl scripts on windows) I managed to set up the production chain:

• write the docmentation in the IDE (Qt Creator)
• process by the perlscript js2doxy.pl
• process the result with Doxygen

However, it took some time until I found out how to write the documentation right.... And here are the rules:

• write a "constructor" function (even if it is not used).
• write the signatures of the functions in javascript; use the special commands for paramters/return values to provide types in the documentation
• assign the function to the prototype (!). This is just to show membership relatiions to the js2doxy-script

Here is an example:

/** DataSource is the basic object to handle input data of various sources.
*/
function DataSource()   // constructor (use  @ctor to add real docmentation)
{ }
 ...
 
/** advance to next record and retrieve content. Returns false, if pointer is located behind the last record.
The next() function provides a efficient looping construct:
@code
// ds: a data source
while (ds.next()) {
   // do something
}
@endcode
@treturn bool Returns false, if pointer is located behind the last record. */
function next() {}
DataSource.prototype.next = next;

/**
opens a datasource with a given \p type from a specific source \p name.
Opens a data source. Writes a output message if opening the data source failed.
@tparam string type Type of the datasource.
@tparam string name path to the file (for file based data sources) or the SQL query for database types.
\sa isOpen() */
function open(type, name) {}
DataSource.prototype.open = open;

Note the way the how datatypes are descibed for the open function, and how code examples are included for the next function. Hopefully soon I will add a link to an example of how such a documentation then looks like in HTML format... This way of documentation is obviously not perfect; however, it allows to separate clearly between source code doc and users doc and is uses the same tools (i.e., Doxygen).