Documentation, documentation, documentation
It is truly said that if you didn’t write it down, it didn’t happen. With that in mind, I’m going to talk about a JavaScript-based mapping service that isn’t Google Maps. Community Mapbuilder is “a range of resources to help organizations get started with standards-based online mapping”. A major part of what they offer is mapbuilder-lib, a set of client-side (and a little sprinkling of server-side) scripts which can talk to map servers using the OpenGIS standards and then display the resulting maps using JavaScript and XSL.
The Community MapBuilder demo may make this a bit clearer; it provides numerous zoomable maps, including a simple one of world countries and another of Mars (!). The zoomable map itself is inserted into the page unobtrusively by the included JavaScript.
This is all standard stuff; it’s a good application of techniques, but the techniques themselves are fairly well-known. The interesting point about mapbuilder-lib is that it’s pretty heavily documented. In addition to some overview technical documentation, the MapBuilder team have provided full and complete API documentation for the whole library, which is really rather helpful for people who are looking to implement mapping applications using MapBuilder. The API documentation is created using JSDoc, which parses through the JavaScript files and extracts documentation from comments in the same way that JavaDoc does for Java files. In essence, when writing the code, the author adds specially formatted comments, like so:
/**
* Get a random colour, really inefficiently
* @returns a random colour name as a string
*/
function randomColour() {
var colours = ['red','blue','green','yellow','heliotrope'];
return colours[parseInt(Math.random()*colours.length)];
}
and then JSDoc extracts the function descriptions, details of what each function returns (indicated by @returns), etc, and builds a browseable HTML set of documentation. JSDoc and similar tools go a long way towards alleviating the burden of writing documentation for an API or a library, and as more web applications and the like are built using DOM scripting, more shared libraries will spring up. Sarissa, the cross-browser XML-handling JavaScript library, also uses JSDoc for documentation, and there are doubtless others. Let’s hope more libraries designed for reuse continue providing good documentation for hackers to use.
