Improving the MapGuide API documentation (part 2)

Don't you bemoan the fact that you need to have the MapGuide API reference on hand because Visual Studio's intellisense doesn't really help you?

With my recent post-RC2 checkins, the intellisense becomes meaningful!

For those who don't know, the MapGuide .net assemblies are not pure .net classes. They are proxy classes to unmanaged C++ classes that reside in various unmanaged dlls that you must remember to copy along with your OSGeo.MapGuide assemblies to your application's output directory. A common rookie mistake is forgetting to copy these additional dlls. Referencing the OSGeo.MapGuide assemblies is not enough, you need to remember to copy these extra dlls.

We use a popular tool called SWIG to create the proxy wrappers not only for .net, but also for PHP and Java (which is how we can have the MapGuide API in these 3 different languages). A major downside to using SWIG is that API documentation fragments get lost in translation, so you always needed to have the API reference on hand if you ever needed to know what a class or method does.

So given these facts, how did we achieve this?

It turns out that doxygen supports XML output of your C++ API documentation, meaning the class and member information gets written to nice and logically structured XML files.

Do you know what else is XML-based? The intellisense documentation files for .net assemblies. When you have two XML-based sources. Moving/translating data from one form to another becomes very simple.

The XML format for a .net assembly intellisense file is actually quite simple

As you can see, it's nothing more than a series of elements describing the various classes, methods and properties of the MapGuide API.

So with the help of a modified version of Doxygen.NET (a .net library that provides an object-oriented API into doxygen's XML output), I wrote a utility that parses the XML output of doxygen and writes out the equivalent .net intellisense XML file. The utility itself was very simple to write because the MapGuide API was designed and in a convention-based manner (needing to have bindings in 3 different languages kind of necessitates this design) and that allows us to make many valid assumptions:

• All .net proxy classes reside under a single namespace (OSGeo.MapGuide) despite being in 5 different physical assemblies.
• Only C++ classes are ever exported. No enums, structs or any other esoteric C++ features.
• Only methods and static fields are exported. No need to handle const correctness, pass-by-reference and other C++-specific ways of calling methods.

This utility produces 5 xml files (one for each OSGeo.MapGuide assembly) that when dropped side-by-side with their respective assembly will cause Visual Studio to use them for documenting any classes and methods that appear in the auto-completion prompt.

The final release of MapGuide Open Source 2.4 will include these intellisense files. In the meantime, you can grab the 5 files from here and drop them beside your MapGuide .net assemblies. If those assemblies are already referenced in a project in an open instance of Visual Studio, you will need to reload that project's solution to get it to pick up the documentation files.

Oh and one more thing. If auto-complete does not show any documentation for a given class or member, it means the main API reference probably doesn't say much either, which goes to show that content-wise the documentation still has lots of room for improvement.