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.

Stuart Langridge has been a Linux user since 1997, and is quite possibly the only person in the world to have a BSc in Computer Science and Philosophy. He’s also one-quarter of the team at LugRadio, the world's premiere Free and Open Source Software radio show. Tony Steidler-Dennison is a Systems Engineer with Rockwell Collins, Inc., designing avionics and cabin data servers for commercial airliners. He’s also the host of The Roadhouse Podcast, "the finest blues you've never heard."

Free Guide:

How to Choose the Right Charting Library for Your Application

How do you make sure that the charting library you choose has everything you need? Sign up to receive this detailed guide from FusionCharts, which explores all the factors you need to consider before making the decision.

  • bwarrene

    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.

  • sil

    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.


    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.

  • Nick

    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!

Learn JavaScript for free!
Free course: Introduction to JavaScript

Yours when you take up a free 14-day SitePoint Premium trial.