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.
February 23rd, 2005 at 10:04 pm
This is probably one of the weakest areas in development projects is substantial documentation. Often it is lacking due to pure exhaustion from limited resources - other times it is a lack of a good technical writer willing to contribute. This kind of documentation should serve as a benchmark for what should be delivered with any application undertaking.
February 24th, 2005 at 2:57 am
That, I confess, is what drove the post; that JSDoc and cohorts do lower the bar to documentation, because it’s not necessarily a whole separate process. While “just add comments and pow! you get documentation!” understates the case somewhat, it’s easier to add the comments, even if they are a little laborious, than it is to produce documentation when you start with a blank page.
March 20th, 2005 at 3:36 pm
As I said working with JSDoc on the command line was a pain in the ass, until I found that little utility JSDocumenter. Which is in fact a GUI for JSDoc. It solved my JavaScript documentation problems in just a second. If you haven’t tried it yet, then you’re losing with every second.
December 16th, 2005 at 6:52 pm
Maybe their developer documentation is great, but the documentation for end-users - i.e. those not wanting to improve MapBuilder is lacking. I’m not saying there isn’t any, but if you are not a JavaScript developer, and just include it in your web pages occasionally for the added flair, getting started as a MapBuilder user can be quite painful. I don’t think I’m alone in feeling this way, based on some comments I’ve seen throughout the MapBuilder-lib website.
Still, great project!