Wednesday, 29 August 2012

Improving the MapGuide API documentation

A majority of you last week said that the MapGuide documentation is one area that definitely has lots of room for improvement, so I went to see what parts of the documentation can at least be improved immediately for the imminent 2.4 release, namely the API documentation.

Here's how the documentation looks with the 2.4 RC1 installation

Which is somewhat of a radical departure from what is currently published on the OSGeo site

It turns out, the one published on the OSGeo site (circa MapGuide Open Source 2.0) used a very ancient version of doxygen to crank out the API documentation. And the documentation as of 2.4 RC1 is the result of incompatibilities of our current doxygen configuration files with the version of doxygen I was using (1.8.0)

So after a bit of tweaking about with the doxygen configs (and a bit of MapGuide public header documentation cleanup and some link fixing), here's what the new MapGuide API documentation looks like:

Despite looking visually cleaner, it's also functionally better as it now has integrated search. Information about a given class or method in the MapGuide API is now just keystrokes away

Not only that, we've fixed up some of the doxygen markup in the headers, allowing us to show you deprecated APIs in the API reference as well (you probably didn't know there's deprecated APIs did you? Well there is, and you should avoid using them wherever possible)

This will appear in the next RC or final release of MapGuide Open Source 2.4. Not fully decided yet whether to make another RC or go straight to final. You'll find out soon enough.

Also got to figure out how to upload new API docs to the OSGeo site.

No comments: