[Mapguide-trac] [mapguide-trac] #2114: Integrated API documentation

[MapGuide Open Source]

#2114: Integrated API documentation
---------------------------+------------------------------------------------
 Reporter:  jng            |         Owner:  jng     
     Type:  enhancement    |        Status:  reopened
 Priority:  medium         |     Milestone:  2.5     
Component:  Documentation  |       Version:          
 Severity:  major          |    Resolution:          
 Keywords:                 |   External_id:          
---------------------------+------------------------------------------------
Changes (by jng):

  * status:  closed => reopened
  * resolution:  fixed =>
  * milestone:  => 2.5


Comment:

 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

-- 
Ticket URL: <http://trac.osgeo.org/mapguide/ticket/2114#comment:2>
MapGuide Open Source <http://mapguide.osgeo.org/>
MapGuide Open Source Internals