Integrated API documentation

[jng]

Doxygen supports XML output, allowing the MapGuide API documentation to be outputted into a logical, machine-processable XML form.

There is a .net object-oriented library for working with doxygen comments in this form (​http://code.google.com/p/doxygen-net/)

With this, it should be possible to build a simple utility that can transform the doxygen XML output into javadoc or .net documentation XML, allowing for inline API documentation in your respective Java/.net IDE

[jng]

Ok I've made a startling discovery in SWIG that would make would make it possible to transplant the doxygen commentary into not just C#, but Java as well, providing a unified integrated API documentation experience for both .net and Java.

We basically (ab)use the SWIG directives javaclassmodifiers/javamethodmodifiers (csclassmodifiers/csmethodmodifiers for C#) to pre-pend the necessary documentation fragments as part of the visibility modifier.

Through this same mechanism, we can also include the .net ObsoleteAttribute and the Java @Deprecated annotation to finally be able to flag deprecation intent in the target language itself! That is to say, a \deprecated note in doxygen on an API can finally translate to a compiler warning in javac/csc when consuming said proxy wrapper API.

For example (Java):

//Adds comments for the class MgCreateSdfParams and includes a @Deprecated annotation
//to trigger compiler warnings.
%typemap(javaclassmodifiers) MgCreateSdfParams %{
/**
 * This class is deprecated
 */
@Deprecated
public%}
//Marks MgMap() ctor as deprecated
%javamethodmodifiers MgMap::MgMap() "@Deprecated public";
//Marks MgFeatureService::DescribeSchema as deprecated
%javamethodmodifiers MgFeatureService::DescribeSchema(MgResourceIdentifier*, STRINGPARAM) "@Deprecated public";

For this to work, either DoxyTransform or IMake needs to be modified to generate the appropriate documentation.i file from the doxygen commentary (translating fragments into the target language's respective documentation format), that then would be included into one of the existing .i files so that its generated directives can then be fed to SWIG.

For simplicity it would be DoxyTransform (as it already understands the doxygen commentary). For portability, it should be IMake

[jng]

Build verification script

[jng]

Fixed with the implementation of RFC129