[mapguide-commits] r7226 - in sandbox/jng/swig-java/BuildTools/WebTools/IMake: . Win32

[svn_mapguide at osgeo.org]

Author: jng
Date: 2012-11-26 02:51:17 -0800 (Mon, 26 Nov 2012)
New Revision: 7226

Modified:
   sandbox/jng/swig-java/BuildTools/WebTools/IMake/IMake.cpp
   sandbox/jng/swig-java/BuildTools/WebTools/IMake/Win32/IMake.exe
Log:
#9, #2114: Add IMake support for:
 - Transplanting javadoc to constant classes (original IMake transplanted doxygen comments verbatim, our work broke this, this submission fixes it properly)
 - Translating the \since directive to JavaDoc
 - Translating the \exception directive to JavaDoc


Modified: sandbox/jng/swig-java/BuildTools/WebTools/IMake/IMake.cpp
===================================================================
--- sandbox/jng/swig-java/BuildTools/WebTools/IMake/IMake.cpp	2012-11-26 08:18:14 UTC (rev 7225)
+++ sandbox/jng/swig-java/BuildTools/WebTools/IMake/IMake.cpp	2012-11-26 10:51:17 UTC (rev 7226)
@@ -542,10 +542,19 @@
 
 string linkifyJavaDocFragment(const string& str)
 {
+    // Explode the fragment into a space delimited list.
+    // Go through the delimited tokens and surround any
+    // token containing "Mg" with {@link <token>} 
+    //
+    // Re-combine each delimited token to form the linkified result
     std::vector<std::string> elems;
     std::stringstream ss(str);
     std::string item;
     while(std::getline(ss, item, ' ')) {
+        //We can't process these yet, so skip them as they may
+        //interfere with doxygen directive translation
+        if (item == "\\link" || item == "\\endlink")
+            continue;
         elems.push_back(item);
     }
     std::string output;
@@ -626,6 +635,14 @@
     // In fact, this technique is documented as a way of transplanting documentation:
     //   http://www.swig.org/Doc1.3/Java.html#javadoc_comments
 
+    // Supported doxygen tags:
+    // \brief - Converted to main javadoc body
+    // \param - @param
+    // \return - @return
+    // \deprecated - Adds the @Deprecated annotation to the class/method declaration (after the converted javadoc)
+    // \since - @since
+    // \exception - @exception
+
     //Re-tokenize the method declaration
     //
     //We want the bits between '(' and ')' (parentheses included) and the first token before the '('
@@ -641,12 +658,14 @@
     std::vector<std::string> descriptionParts;
     std::vector<std::string> paramParts;
     std::vector<std::string> returnParts;
+    std::string sinceVer;
+    std::vector<std::string> exceptionParts;
 
     while(i < elems.size()) {
         if (elems[i].find("<!-- Syntax in .Net, Java, and PHP -->") != std::string::npos ||
             elems[i].find("<!-- Example (PHP) -->") != std::string::npos ||
             elems[i].find("<!-- Example (Java) -->") != std::string::npos ||
-            elems[i].find("<!-- Example (DotNet) -->") != std::string::npos) {
+            elems[i].find("<!-- Example (C#) -->") != std::string::npos) {
             i++;
             continue;
         }
@@ -658,7 +677,7 @@
                 if (elems[i].find("<!-- Syntax in .Net, Java, and PHP -->") != std::string::npos ||
                     elems[i].find("<!-- Example (PHP) -->") != std::string::npos ||
                     elems[i].find("<!-- Example (Java) -->") != std::string::npos ||
-                    elems[i].find("<!-- Example (DotNet) -->") != std::string::npos) {
+                    elems[i].find("<!-- Example (C#) -->") != std::string::npos) {
                     i++;
                     continue;
                 }
@@ -693,7 +712,7 @@
                 if (elems[i].find("<!-- Syntax in .Net, Java, and PHP -->") != std::string::npos ||
                     elems[i].find("<!-- Example (PHP) -->") != std::string::npos ||
                     elems[i].find("<!-- Example (Java) -->") != std::string::npos ||
-                    elems[i].find("<!-- Example (DotNet) -->") != std::string::npos) {
+                    elems[i].find("<!-- Example (C#) -->") != std::string::npos) {
                     i++;
                     continue;
                 }
@@ -709,6 +728,17 @@
             isDeprecated = true;
             continue;
         }
+        else if (elems[i].find("\\since") != std::string::npos) {
+            sinceVer = elems[i].substr(elems[i].find("\\since") + 6);
+            i++;
+            continue;
+        }
+        else if (elems[i].find("\\exception") != std::string::npos) {
+            std::string except = elems[i].substr(elems[i].find("\\exception") + 10);
+            exceptionParts.push_back(except);
+            i++;
+            continue;
+        }
         i++;
     }
 
@@ -723,7 +753,7 @@
         }
         javaDoc.append(" *\n");
     } else {
-        javaDoc.append(" * TODO: Missing API Documentation here (message inserted by IMake.exe)\n");
+        javaDoc.append(" * TODO: API Documentation is missing or failed to translate doxygen brief directive (message inserted by IMake.exe)\n");
     }
 
     if (paramParts.size() > 0) {
@@ -744,6 +774,19 @@
         javaDoc.append("\n");
     }
 
+    if (exceptionParts.size() > 0) {
+        for (int i = 0; i < exceptionParts.size(); i++) {
+            javaDoc.append(" * @exception ");
+            javaDoc.append(exceptionParts[i]);
+            javaDoc.append("\n");
+        }
+    }
+
+    if (!sinceVer.empty()) {
+        javaDoc.append(" * @since ");
+        javaDoc.append(sinceVer);
+    }
+
     // ---------------------- JAVADOC END ------------------------ //
     javaDoc.append(" */\n");
     if (isDeprecated)
@@ -913,6 +956,22 @@
                 firstToken = true;
                 continue;
             }
+            if (firstToken)
+            {
+                if (translateMode && !commentStr.empty()) 
+                {
+                    string convertedDoc;
+                    if (language == java) {
+                        convertedDoc = doxygenToJavaDoc(commentStr);
+                        fprintf(outfile, "%s\n   ", convertedDoc.c_str());
+                    } else if (language == csharp) {
+                        convertedDoc = doxygenToCsharpDoc(commentStr);
+                        fprintf(outfile, "%s\n   ", convertedDoc.c_str());
+                    }
+                    commentStr.clear();
+                }
+            }
+
             if(firstToken && (language == java || language == csharp))
             {
                 fprintf(outfile, "public ");
@@ -1142,9 +1201,6 @@
         //printf("Processing header: %s\n", className.c_str());
         if(!ignore)
         {
-            //TODO: The transplanted comments are meaningless both java/csharp contexts because the the documentation
-            //format is incompatible with javadoc/.net XML documentation
-
             if(translateMode)
             {
                 if(language == java)
@@ -1185,7 +1241,14 @@
 
                 if (!commentStr.empty()) 
                 {
-                    fprintf(outfile, "%s", commentStr.c_str());
+                    string convertedDoc;
+                    if (language == java) {
+                        convertedDoc = doxygenToJavaDoc(commentStr);
+                        fprintf(outfile, "%s", convertedDoc.c_str());
+                    } else if (language == csharp) {
+                        convertedDoc = doxygenToCsharpDoc(commentStr);
+                        fprintf(outfile, "%s", convertedDoc.c_str());
+                    }
                 }
             }
 

Modified: sandbox/jng/swig-java/BuildTools/WebTools/IMake/Win32/IMake.exe
===================================================================
(Binary files differ)