Major refactoring: translation now takes a node and returns a translated comment if there is one.

This is to allow for situations where you need to use several nodes to create a comment, for example where there are multiple overloads for the same function but the target language doesnt support overloading: in this case we want to combine comments to explain the possible overloads.


git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-cherylfoil@10843 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Source/DoxygenTranslator/src/DoxygenTranslator.cpp

@@ -1,43 +1,32 @@
-#include "DoxygenParser.h"
+/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * DoxygenTranslator.cpp
+ *
+ * Module to return documentation for nodes formatted for various documentation
+ * systems.
+ * ----------------------------------------------------------------------------- */
+
 #include "DoxygenTranslator.h"
-#include <cstdlib>
-#include <iostream>
-#include <string>
-#include "DoxygenEntity.h"
 #include "JavaDocConverter.h"
 #include "PyDocConverter.h"
 
-DoxygenParser doxyParse;
+bool DoxygenTranslator::getDocumentation(Node *node, DocumentationFormat format, String *&documentation){
-JavaDocConverter jDC;
+  switch(format){
-PyDocConverter pyDC;
+    case JavaDoc:   
-
+      return JavaDocConverter().getDocumentation(node, documentation);
-DoxygenTranslator::DoxygenTranslator(){
+    case PyDoc:   
-	doxyParse = DoxygenParser();
+      return PyDocConverter().getDocumentation(node, documentation);
-    JavaDocConverter jDC = JavaDocConverter();
+    default:
-    PyDocConverter pyDC = PyDocConverter();
+      return false;
-}
+  }
-
-DoxygenTranslator::~DoxygenTranslator(){
-	
-}
-
-
-char *DoxygenTranslator::convert(Node *n, char* doxygenBlob, char* option){
-	
-  std::list <DoxygenEntity> rootList = doxyParse.createTree(std::string(doxygenBlob));
-  std::string returnedString;
-  
-  if(strcmp(option, "JAVADOC") == 0)
-    returnedString = jDC.convertToJavaDoc(n, rootList);
-  else if(strcmp(option, "PYDOC") == 0)
-    returnedString = pyDC.convertToPyDoc(n, rootList);
-  else 
-    std::cout << "Option not current supported." << std::endl;
-	
-  char *nonConstString;
-  nonConstString = (char *)malloc(returnedString.length() + 1);
-  strcpy(nonConstString, returnedString.c_str());
-  
-  return nonConstString;
 }
 
+void DoxygenTranslator::printTree(std::list<DoxygenEntity> &entityList){  
+  std::list<DoxygenEntity>::iterator p = entityList.begin();
+  while (p != entityList.end()){
+    (*p).printEntity(0);
+    p++;
+  }
+}

Source/DoxygenTranslator/src/DoxygenTranslator.h

@@ -1,13 +1,65 @@
+/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * DoxygenTranslator.h
+ *
+ * Module to return documentation for nodes formatted for various documentation
+ * systems.
+ * ----------------------------------------------------------------------------- */
+
 #ifndef DOXYGENTRANSLATOR_H_
 #define DOXYGENTRANSLATOR_H_
 
 #include "swig.h"
+#include "DoxygenEntity.h"
+#include <list>
 
+/*
+ * Describes the availible documentation systems
+ * that can be translated to.
+ */
+enum DocumentationFormat {
+  JavaDoc = 1,
+  PyDoc = 2
+};
+
+/*
+ * A class to translate doxygen comments attacted to parser nodes
+ * into alternative formats for use in code generated for target languages.
+ */
 class DoxygenTranslator
 {
 public:
-	DoxygenTranslator();
+  /*
-	virtual ~DoxygenTranslator();
+   * Virtual destructor.
-	char* convert(Node *n, char* doxygenBlob, char* option);
+   */
+  virtual ~DoxygenTranslator(){}
+  
+  /*
+   * Return the documentation for a given node formated for the correct 
+   * documentation system.
+   * @param node The node to extract and translate documentation for.
+   * @param format The documentation format to output.
+   * @param documentation The returned documentation string.
+   * @return A bool to indicate if there was documentation to return for the node.
+   */
+  static bool getDocumentation(Node *node, DocumentationFormat format, String *&documentation);
+  
+protected:
+  /*
+   * Overridden in subclasses to return the documentation formatted for a given
+   * documentation system.
+   * @param node The node to extract and translate documentation for.
+   * @param documentation The returned documentation string.
+   * @return A bool to indicate if there was documentation to return for the node.
+   */
+  virtual bool getDocumentation(Node *node, String *&documentation) = 0;
+  
+  /*
+   * Prints the details of a parsed entity list to stdout (for debugging).
+   */
+  void printTree(std::list<DoxygenEntity> &entityList);
 };
+
 #endif /*DOXYGENTRANSLATOR_H_*/

Source/DoxygenTranslator/src/JavaDocConverter.cpp

@@ -1,31 +1,17 @@
 #include "JavaDocConverter.h"
+#include "DoxygenParser.h"
 #include <iostream>
 #define APPROX_LINE_LENGTH 64//characters per line allowed
 #define TAB_SIZE 8//characters per line allowed
 int printSortedTree2 = 0;
 //TODO {@link} {@linkplain} {@docRoot}, and other useful doxy commands that are not a javadoc tag
-JavaDocConverter::JavaDocConverter()
-{
-}
 
-JavaDocConverter::~JavaDocConverter()
+std::string JavaDocConverter::formatCommand(std::string unformattedLine, int indent){
-{
-}
-
-void JavaDocConverter::printSortedTree(std::list<DoxygenEntity> &entityList){
-  std::list<DoxygenEntity>::iterator p = entityList.begin();
-  while (p != entityList.end()){
-    (*p).printEntity(0);
-    p++;
-  }
-}
-
-std::string formatCommand(std::string unformattedLine, int indent){
   std::string formattedLines = "\n * ";
   int lastPosition = 0;
   int i = 0;
   int isFirstLine  = 1;
-  while (i != -1 && i < unformattedLine.length()){
+  while (i != -1 && i < (int)unformattedLine.length()){
     lastPosition = i;
     if (isFirstLine){
       i+=APPROX_LINE_LENGTH;
@@ -33,7 +19,7 @@ std::string formatCommand(std::string unformattedLine, int indent){
     else i+=APPROX_LINE_LENGTH - indent*TAB_SIZE;
     i = unformattedLine.find(" ", i);
 
-    if (i > 0 && i + 1 < unformattedLine.length()){
+    if (i > 0 && i + 1 < (int)unformattedLine.length()){
       if (!isFirstLine) for (int j = 0; j < indent; j++) {
         formattedLines.append("\t");
         }
@@ -45,7 +31,7 @@ std::string formatCommand(std::string unformattedLine, int indent){
 
     }
   }
-  if (lastPosition < unformattedLine.length()){
+  if (lastPosition < (int)unformattedLine.length()){
     if (!isFirstLine) {for (int j = 0; j < indent; j++) {formattedLines.append("\t");}}
     formattedLines.append(unformattedLine.substr(lastPosition, unformattedLine.length() - lastPosition));
   }
@@ -56,7 +42,7 @@ std::string formatCommand(std::string unformattedLine, int indent){
 /* Contains the conversions for tags
  * could probably be much more efficient...
  */
-std::string javaDocFormat(DoxygenEntity &doxygenEntity){
+std::string JavaDocConverter::javaDocFormat(DoxygenEntity &doxygenEntity){
   if(doxygenEntity.typeOfEntity.compare("partofdescription") == 0){
         return doxygenEntity.data;
     }
@@ -97,7 +83,7 @@ std::string javaDocFormat(DoxygenEntity &doxygenEntity){
 }
 
 
-std::string translateSubtree( DoxygenEntity &doxygenEntity){
+std::string JavaDocConverter::translateSubtree( DoxygenEntity &doxygenEntity){
   std::string returnedString;
   if (doxygenEntity.isLeaf){ return javaDocFormat(doxygenEntity) + " ";}
   else {
@@ -111,7 +97,7 @@ std::string translateSubtree( DoxygenEntity &doxygenEntity){
   return returnedString;
 }
 
-std::string translateEntity(DoxygenEntity &doxyEntity){
+std::string JavaDocConverter::translateEntity(DoxygenEntity &doxyEntity){
   if(doxyEntity.typeOfEntity.compare("partofdescription")== 0) return formatCommand(std::string(translateSubtree(doxyEntity)), 0);
   if ((doxyEntity.typeOfEntity.compare("brief") == 0)||(doxyEntity.typeOfEntity.compare("details") == 0)){
   return formatCommand(std::string(translateSubtree(doxyEntity)), 0) + "\n * ";}
@@ -136,13 +122,19 @@ std::string translateEntity(DoxygenEntity &doxyEntity){
   return "";
 }
 
-std::string JavaDocConverter:: convertToJavaDoc(Node *n, std::list <DoxygenEntity> entityList){
+bool JavaDocConverter::getDocumentation(Node *n, String *&documentation){
-  #pragma unused(n)
+  documentation = Getattr(n,"DoxygenComment");
+  if(documentation == NULL)
+    return false;
+  
+  std::list <DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
+  Delete(documentation);
+  
   entityList.sort(CompareDoxygenEntities());
   
-  if(printSortedTree2){
+  if(debug){
     std::cout << "---RESORTED LIST---" << std::endl;
-    printSortedTree(entityList);
+    printTree(entityList);
   }
 
   std::string javaDocString = "/**";
@@ -154,10 +146,11 @@ std::string JavaDocConverter:: convertToJavaDoc(Node *n, std::list <DoxygenEntit
 
   javaDocString += "\n */\n";
   
-  if(printSortedTree2){
+  if(debug){
     std::cout << "\n---RESULT IN JAVADOC---" << std::endl;
     std::cout << javaDocString; 
   }
   
-  return javaDocString;
+  documentation = NewString(javaDocString.c_str());
-}
+  return true;
+}

Source/DoxygenTranslator/src/JavaDocConverter.h

@@ -1,18 +1,34 @@
+/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * JavaDocConverter.h
+ *
+ * Module to return documentation for nodes formatted for JavaDoc
+ * ----------------------------------------------------------------------------- */
+
 #ifndef JAVADOCCONVERTER_H_
 #define JAVADOCCONVERTER_H_
 
-#include <list>
+#include "DoxygenTranslator.h"
-#include <string>
-#include "swig.h"
-#include "DoxygenEntity.h"
 
-class JavaDocConverter
+/*
+ * A class to translate doxygen comments into JavaDoc style comments.
+ */
+class JavaDocConverter : public DoxygenTranslator
 {
 public:
-  JavaDocConverter();
+  JavaDocConverter() : debug( true ){}
-  std::string convertToJavaDoc(Node *n, std::list <DoxygenEntity> entityList);
+  virtual bool getDocumentation(Node *node, String *&documentation);
-  ~JavaDocConverter();
+  
-  void printSortedTree(std::list <DoxygenEntity> &entityList);
+protected:
+  std::string formatCommand(std::string unformattedLine, int indent);
+  std::string translateEntity(DoxygenEntity &doxyEntity);
+  std::string javaDocFormat(DoxygenEntity &doxygenEntity);
+  std::string translateSubtree( DoxygenEntity &doxygenEntity);
+  
+private:
+  bool debug;
 };
 
 #endif /*JAVADOCCONVERTER_H_*/

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -1,4 +1,14 @@
+/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * PyDocConverter.cpp
+ *
+ * Module to return documentation for nodes formatted for PyDoc
+ * ----------------------------------------------------------------------------- */
+
 #include "PyDocConverter.h"
+#include "DoxygenParser.h"
 #include <iostream>
 #include <sstream>
 
@@ -8,18 +18,6 @@ PyDocConverter::PyDocConverter()
     debug = 1;
 }
 
-PyDocConverter::~PyDocConverter()
-{
-}
- 
-void PyDocConverter::printTree(std::list <DoxygenEntity> &entityList){
-  std::list<DoxygenEntity>::iterator p = entityList.begin();
-  while (p != entityList.end()){
-    (*p).printEntity(0);
-    p++;
-  }
-}
-
 std::string PyDocConverter::formatParam(Node *n, DoxygenEntity &doxygenEntity) {
   ParmList *plist = CopyParmList(Getattr(n, "parms"));
   Parm *p = NULL;
@@ -28,7 +26,7 @@ std::string PyDocConverter::formatParam(Node *n, DoxygenEntity &doxygenEntity) {
   DoxygenEntity& paramDescriptionEntity = *(++doxygenEntity.entityList.begin());
   
   std::string result;
-  std::string paramDescription = formatCommand(paramDescriptionEntity.data, DOC_PARAM_STRING_LENGTH);
+  std::string paramDescription = justifyString(paramDescriptionEntity.data, DOC_PARAM_STRING_LENGTH);
   
   for (p = plist; p;) {
     if(Char(Getattr(p, "name")) == paramNameEntity.data) {
@@ -47,7 +45,12 @@ std::string PyDocConverter::formatParam(Node *n, DoxygenEntity &doxygenEntity) {
   return result;
 }
 
-std::string PyDocConverter::formatCommand(std::string documentString, int indent, int maxWidth){
+std::string PyDocConverter::formatReturnDescription(Node *node, DoxygenEntity &doxygenEntity){
+#pragma unused(node)
+  return "\nResult:\n" + justifyString(translateSubtree(doxygenEntity));
+}
+
+std::string PyDocConverter::justifyString(std::string documentString, int indent, int maxWidth){
   std::ostringstream formattedString;
   std::string currentLine;
   
@@ -85,24 +88,24 @@ std::string PyDocConverter::translateSubtree( DoxygenEntity &doxygenEntity){
 
 std::string PyDocConverter::translateEntity(Node *n, DoxygenEntity &doxyEntity){
   if(doxyEntity.typeOfEntity.compare("partofdescription")== 0) 
-    return formatCommand(std::string(translateSubtree(doxyEntity)), 0);
+    return justifyString(std::string(translateSubtree(doxyEntity)), 0);
   
   if ((doxyEntity.typeOfEntity.compare("brief") == 0)||(doxyEntity.typeOfEntity.compare("details") == 0)){
-    return formatCommand(std::string(translateSubtree(doxyEntity)), 0) + "\n * ";}
+    return justifyString(std::string(translateSubtree(doxyEntity)), 0) + "\n * ";}
   
   if(doxyEntity.typeOfEntity.compare("plainstd::string")== 0 
     || doxyEntity.typeOfEntity.compare("deprecated")== 0 
     || doxyEntity.typeOfEntity.compare("brief")== 0)
-    return formatCommand(doxyEntity.data, 0) + "\n * ";
+    return justifyString(doxyEntity.data, 0) + "\n * ";
   
   if(doxyEntity.typeOfEntity.compare("see") == 0)
-    return formatCommand(std::string("@" + doxyEntity.typeOfEntity + "\t\t" + translateSubtree(doxyEntity)), 2);
+    return justifyString(std::string("@" + doxyEntity.typeOfEntity + "\t\t" + translateSubtree(doxyEntity)), 2);
   
   if(doxyEntity.typeOfEntity.compare("param") == 0)
     return formatParam(n, doxyEntity);
   
   if(doxyEntity.typeOfEntity.compare("return")== 0)
-    
+    return formatReturnDescription(n, doxyEntity);
 
   if(doxyEntity.typeOfEntity.compare("author")== 0
     || doxyEntity.typeOfEntity.compare("param")== 0
@@ -110,15 +113,22 @@ std::string PyDocConverter::translateEntity(Node *n, DoxygenEntity &doxyEntity){
     || doxyEntity.typeOfEntity.compare("version")== 0
     || doxyEntity.typeOfEntity.compare("exception") == 0
     || doxyEntity.typeOfEntity.compare("deprecated") == 0)
-    return formatCommand(std::string("@" + doxyEntity.typeOfEntity + "\t" + translateSubtree(doxyEntity)), 2);
+    return justifyString(std::string("@" + doxyEntity.typeOfEntity + "\t" + translateSubtree(doxyEntity)), 2);
   
   if(doxyEntity.typeOfEntity.compare("sa")== 0)
-    return formatCommand(std::string("@see\t\t" + translateSubtree(doxyEntity)), 2);
+    return justifyString(std::string("@see\t\t" + translateSubtree(doxyEntity)), 2);
 
-  return formatCommand(doxyEntity.data, 0);
+  return justifyString(doxyEntity.data);
 }
 
-std::string PyDocConverter::convertToPyDoc(Node *n, std::list<DoxygenEntity> entityList){
+bool PyDocConverter::getDocumentation(Node *n, String *&documentation){
+  documentation = Getattr(n,"DoxygenComment");
+  if(documentation == NULL)
+    return false;
+  
+  std::list <DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
+  Delete(documentation);
+  
   std::string pyDocString = "\"\"\"\n";
   
   bool inParamsSection = false;
@@ -144,5 +154,6 @@ std::string PyDocConverter::convertToPyDoc(Node *n, std::list<DoxygenEntity> ent
     std::cout << std::endl;
   }
   
-  return pyDocString;
+  documentation = NewString(pyDocString.c_str());
+  return true;
 }

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -1,3 +1,12 @@
+/* -----------------------------------------------------------------------------
+ * See the LICENSE file for information on copyright, usage and redistribution
+ * of SWIG, and the README file for authors - http://www.swig.org/release.html.
+ *
+ * PyDocConverter.h
+ *
+ * Module to return documentation for nodes formatted for PyDoc
+ * ----------------------------------------------------------------------------- */
+
 #ifndef PYDOCCONVERTER_H_
 #define PYDOCCONVERTER_H_
 
@@ -5,21 +14,41 @@
 #include <string>
 #include "swig.h"
 #include "DoxygenEntity.h"
+#include "DoxygenTranslator.h"
 
 #define DOC_STRING_LENGTH	  64  // characters per line allowed
 #define DOC_PARAM_STRING_LENGTH	  30  // characters reserved for param name / type
 
-class PyDocConverter
+class PyDocConverter : public DoxygenTranslator
 {
 public:
   PyDocConverter();
-  std::string convertToPyDoc(Node *n, std::list <DoxygenEntity> entityList);
+  bool getDocumentation(Node *node, String *&documentation);
-  ~PyDocConverter();
+  
-  void printTree(std::list <DoxygenEntity> &entityList);
-
 protected:
-  std::string formatParam(Node *n, DoxygenEntity &doxygenEntity);
+  /*
-  std::string formatCommand(std::string unformattedLine, int indent, int maxWidth = DOC_STRING_LENGTH);
+   * Format the doxygen comment relating to a function or method parameter
+   * @param node The parse tree node that the parameter relates to.
+   * @param doxygenEntity The doxygen entity relating to the parameter docstring.
+   */
+  std::string formatParam(Node *node, DoxygenEntity &doxygenEntity);
+  
+  /*
+   * Format the doxygen comment relating to the return value for a method or function.
+   * @param node The parse tree node that the parameter relates to.
+   * @param doxygenEntity The doxygen entity relating to the parameter docstring.
+   */
+  std::string formatReturnDescription(Node *node, DoxygenEntity &doxygenEntity);
+  
+  /*
+   * Format a string so it is justified and split over several lines 
+   * not exeeding a given length.
+   * @param unformattedLine The string to justify and split.
+   * @param indent An optional number of spaces to indent each line by.
+   * @param maxWidth The approximate maximum line width.
+   */
+  std::string justifyString(std::string unformattedLine, int indent = 0, int maxWidth = DOC_STRING_LENGTH);
+  
   std::string translateSubtree( DoxygenEntity &doxygenEntity);
   std::string translateEntity(Node *n, DoxygenEntity &doxyEntity);
     

Source/Modules/java.cxx

@@ -91,10 +91,6 @@ class JAVA:public Language {
     Setline(p, Getline(n));
     return p;
   }
-  /* DOXYGEN TO JAVADOC globals */
-  //TODO make this bool a command line option
-  DoxygenTranslator doxyTranslator;
-
 
 public:
 
@@ -124,7 +120,7 @@ public:
       global_variable_flag(false),
       old_variable_names(false),
       member_func_flag(false),
-	  doxygen_javadoc_flag(true),
+      doxygen_javadoc_flag(true),
       comment_creation_chatter(false),
       imclass_name(NULL),
       module_class_name(NULL),
@@ -160,7 +156,6 @@ public:
        should be easy to implement though */
     director_multiple_inheritance = 0;
     director_language = 1;
-    doxyTranslator = DoxygenTranslator();
   }
 
   /* -----------------------------------------------------------------------------
@@ -508,12 +503,13 @@ public:
 	Printf(f_module, "%s\n", module_imports);
       
       if (doxygen_javadoc_flag){
-      	if (Getattr(n,"DoxygenComment")){
+	String *doxygen_comments;
-      		  if(comment_creation_chatter) Printf(f_module, "/* This was generated from top() */");
+	if(DoxygenTranslator::getDocumentation(n, JavaDoc,doxygen_comments)){
-      		  char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");
+	  if(comment_creation_chatter)
-      		  Printf(f_module, convertedString); 	
+	    Printf(f_module, "/* This was generated from top() */");
-      		  free(convertedString);
+	  Printf(f_module, Char(doxygen_comments)); 
-      	}
+	  Delete(doxygen_comments);
+	}
       }
       if (Len(module_class_modifiers) > 0)
 	Printf(f_module, "%s ", module_class_modifiers);
@@ -1234,15 +1230,17 @@ public:
 	  // Add extra indentation
 	  Replaceall(enum_code, "\n", "\n  ");
 	  Replaceall(enum_code, "  \n", "\n");
-	    //translate and write javadoc comment if flagged
+	  
-	    if (doxygen_javadoc_flag){
+	  //translate and write javadoc comment if flagged
-	    	if (Getattr(n,"DoxygenComment")){
+	  if (doxygen_javadoc_flag){
-	    		if(comment_creation_chatter) Printv(proxy_class_constants_code, "/* This was generated from enumvalueDeclaration */", NIL );
+	    String *doxygen_comments;
-	    		char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");
+	    if(DoxygenTranslator::getDocumentation(n, JavaDoc,doxygen_comments)){
-	    		Printv(proxy_class_constants_code, convertedString, NIL); 	
+	      if(comment_creation_chatter)
-	    		free(convertedString); 
+		Printf(proxy_class_constants_code, "/* This was generated from enumvalueDeclaration() */");
-	    	}
+	      Printf(proxy_class_constants_code, Char(doxygen_comments)); 
+	      Delete(doxygen_comments);
 	    }
+	  }
 	    
 	  Printv(proxy_class_constants_code, "  ", enum_code, "\n\n", NIL);
 	} else {
@@ -1308,12 +1306,13 @@ public:
     
     //translate and write javadoc comment if flagged
     if (doxygen_javadoc_flag){
-    	if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-    		  if(comment_creation_chatter) Printf(enum_code, "/* This was generated from enumvalueDeclaration() */" );
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc,doxygen_comments)){
-	    	  char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");		
+	if(comment_creation_chatter)
-    		  Printf(enum_code, convertedString); 	
+	  Printf(enum_code, "/* This was generated from enumvalueDeclaration() */");
-    		  free(convertedString); 
+	Printf(enum_code, Char(doxygen_comments)); 
-    	}
+	Delete(doxygen_comments);
+      }
     }
     {
       EnumFeature enum_feature = decodeEnumFeature(parentNode(n));
@@ -1379,15 +1378,16 @@ public:
    * file
    * ------------------------------------------------------------------------ */
   virtual int doxygenComment(Node *n){
-		 if (doxygen_javadoc_flag){
+    if (doxygen_javadoc_flag){
-		   if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-			      if(comment_creation_chatter) Printv(structuralComments, "/* This was generated from doxygenComment() */\n", NIL);
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-		    	  char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	if(comment_creation_chatter)
-			      Printv(structuralComments, convertedString, NIL);
+	  Printf(structuralComments, "/* This was generated from doxygenComment() */");
-			      free(convertedString);
+	Printf(structuralComments, Char(doxygen_comments)); 
-		    	}
+	Delete(doxygen_comments);
-		    }
+      }
-	 return SWIG_OK;
+    }
+    return SWIG_OK;
   }
   
   /* -----------------------------------------------------------------------
@@ -1408,14 +1408,16 @@ public:
     String *tm;
     String *return_type = NewString("");
     String *constants_code = NewString("");
+    
     //translate and write javadoc comment if flagged
     if (doxygen_javadoc_flag){
-    	if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-    		if(comment_creation_chatter) Printf(constants_code, "/* This was generated from enumvalueDeclaration */\n");
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-	    	char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	if(comment_creation_chatter)
-            Printf(constants_code, convertedString); 	
+	  Printf(constants_code, "/* This was generated from constantWrapper() */");
-		    free(convertedString);
+	Printf(constants_code, Char(doxygen_comments)); 
-    	}
+	Delete(doxygen_comments);
+      }
     }
     
     if (!addSymbol(symname, n))
@@ -1681,12 +1683,13 @@ public:
     
     //translate and write javadoc comment if flagged
     if (doxygen_javadoc_flag){
-    	if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-    		if(comment_creation_chatter) Printv(proxy_class_def, "/* This was generated from emitProxyClassDefAndCPPCasts() */\n", NIL );
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-	    	char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	if(comment_creation_chatter)
-	    	Printv(proxy_class_def, convertedString, NIL); 		
+	  Printf(proxy_class_def, "/* This was generated from emitProxyClassDefAndCPPCasts() */");
-		    free(convertedString);
+	Printf(proxy_class_def, Char(doxygen_comments)); 
-    	}
+	Delete(doxygen_comments);
+      }
     }
     
     // Start writing the proxy class
@@ -2021,15 +2024,15 @@ public:
       setter_flag = (Cmp(Getattr(n, "sym:name"), Swig_name_set(Swig_name_member(proxy_class_name, variable_name))) == 0);
     }
     
-    
     //translate and write javadoc comment if flagged
     if (doxygen_javadoc_flag){
-    	if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-    		if(comment_creation_chatter) Printf(function_code, "/* This was generated from proxyclassfunctionhandler */");
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-  	    	char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	if(comment_creation_chatter)
-  	    	 Printf(function_code, convertedString); 		
+	  Printf(function_code, "/* This was generated from proxyclassfunctionhandler() */");
-  		    free(convertedString);
+	Printf(function_code, Char(doxygen_comments)); 
-    	}
+	Delete(doxygen_comments);
+      }
     }
     
     /* Start generating the proxy function */
@@ -2254,15 +2257,16 @@ public:
       tm = Getattr(n, "tmap:jtype"); // typemaps were attached earlier to the node
       Printf(im_return_type, "%s", tm);
       
-	    //translate and write javadoc comment if flagged
+      //translate and write javadoc comment if flagged
-	    if (doxygen_javadoc_flag){
+      if (doxygen_javadoc_flag){
-	    	if (Getattr(n,"DoxygenComment")){
+	String *doxygen_comments;
-	    		if(comment_creation_chatter) Printf(function_code, "/* This was generated from constructionhandler */\n" );
+	if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-	  	    	char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	  if(comment_creation_chatter)
-	  	    	Printf(function_code, convertedString); 			
+	    Printf(function_code, "/* This was generated from constructionhandler() */");
-		  		free(convertedString);
+	  Printf(function_code, Char(doxygen_comments)); 
-	    	}
+	  Delete(doxygen_comments);
-	    }
+	}
+      }
 	    
       Printf(function_code, "  %s %s(", methodmods, proxy_class_name);
       Printf(helper_code, "  static private %s SwigConstruct%s(", im_return_type, proxy_class_name);
@@ -2525,14 +2529,15 @@ public:
     String *pre_code = NewString("");
     String *post_code = NewString("");
     
-    //translate and write javadoc comment if flagged
+    // translate and write javadoc comment if flagged
     if (doxygen_javadoc_flag){
-    	if (Getattr(n,"DoxygenComment")){
+      String *doxygen_comments;
-    		if(comment_creation_chatter) Printf(function_code, "/* This was generated from moduleClassFunctionHandler() */\n" );
+      if(DoxygenTranslator::getDocumentation(n, JavaDoc, doxygen_comments)){
-  	    	char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")),"JAVADOC");			
+	if(comment_creation_chatter)
-  	    	Printf(function_code, convertedString); 			
+	  Printf(function_code, "/* This was generated from moduleClassFunctionHandler() */");
-	  		free(convertedString);	
+	Printf(function_code, Char(doxygen_comments)); 
-    	}
+	Delete(doxygen_comments);
+      }
     }
 
     if (l) {

Source/Modules/python.cxx

@@ -18,6 +18,7 @@ char cvsroot_python_cxx[] = "$Id: python.cxx 10453 2008-05-15 21:18:44Z wsfulton
 static int treduce = SWIG_cparse_template_reduce(0);
 
 #include <ctype.h>
+#include <sstream>
 #include "../DoxygenTranslator/src/DoxygenTranslator.h"
 
 #define PYSHADOW_MEMBER  0x2
@@ -85,8 +86,6 @@ static int extranative = 0;
 static int outputtuple = 0;
 static int nortti = 0;
 
-static DoxygenTranslator doxyTranslator;
-
 /* flags for the make_autodoc function */
 enum autodoc_t {
   AUTODOC_CLASS,
@@ -2906,19 +2905,18 @@ public:
         }
       }
       Printf(f_shadow, ":\n");
-		
+      
-	//translate and write pydoc comment if flagged
+      // translate and write pydoc comment if flagged
-	if (doxygen){
+      if (doxygen){
-		if (Getattr(n,"DoxygenComment")){
+	String *doxygen_comments;
-			//if(comment_creation_chatter) Printf(function_code, "/* This was generated from classHandler */");
+	if(DoxygenTranslator::getDocumentation(n, PyDoc, doxygen_comments)){
-			char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")), "PYDOC");			
+	  Printf(f_shadow, Char(pythoncode(doxygen_comments, shadow_indent))); 
-			Printf(f_shadow, Char(pythoncode(convertedString, shadow_indent))); 		
+	  Delete(doxygen_comments);
-			free(convertedString);
-		}
 	}
+      }
 	
-	// otherwise use default docstrings if requested
+      // otherwise use default docstrings if requested
-	else if (have_docstring(n)) {
+      else if (have_docstring(n)) {
 	String *str = docstring(n, AUTODOC_CLASS, tab4);
 	if (str != NULL && Len(str))
 	  Printv(f_shadow, tab4, str, "\n", NIL);
@@ -3130,15 +3128,33 @@ public:
 	  } else {
 	    Printv(f_shadow, tab4, "def ", symname, "(",parms , ")", returnTypeAnnotation(n), ":", NIL);
 	    Printv(f_shadow, "\n", NIL);
-		if (doxygen) {
+	    if (doxygen) {
-			if (Getattr(n,"DoxygenComment")){
+	      /*Node *documented_node = n;
-				//if(comment_creation_chatter) Printf(function_code, "/* This was generated from classHandler */");
+	      if(Getattr(n, "sym:overloaded")){
-				char *convertedString = doxyTranslator.convert(n, Char(Getattr(n,"DoxygenComment")), "PYDOC");			
+		// If the function is overloaded then this funciton is called
-				Printf(f_shadow, Char(pythoncode(convertedString, tab8))); 		
+		// for the last one.  Rewind to the first so the docstrings are
-				free(convertedString);
+		// in order.
-			}
+		while (Getattr(documented_node, "sym:previousSibling"))
+		  documented_node = Getattr(documented_node, "sym:previousSibling");
+		
+		int real_overload_count = 0;
+		std::ostringstream all_documentation;
+		
+		// for each real method (not a generated overload) append the documentation
+		while(documented_node){
+		  if(!is_generated_overload(documented_node) && Getattr(documented_node,"DoxygenComment")){
+		    all_documentation << "Overload " << ++real_overload_count << ":" << std::endl;
+		    all_documentation << Char(Getattr(documented_node,"DoxygenComment")) << std::endl;
+		  }
+		  documented_node = Getattr(documented_node, "sym:nextSibling");
 		}
-	    if (have_docstring(n))
+		
+		char *convertedString = doxyTranslator.convert(n,const_cast< char *>(all_documentation.str().c_str()), "PYDOC");	
+		Printf(f_shadow, Char(pythoncode(convertedString, tab8))); 		
+		free(convertedString);
+	      }*/
+	    }
+	    else if (have_docstring(n))
 	      Printv(f_shadow, tab8, docstring(n, AUTODOC_METHOD, tab8), "\n", NIL);
 	    if (have_pythonprepend(n)) {
 	      fproxy = 0;

Source/Swig/misc.c

@@ -1032,6 +1032,17 @@ String *Swig_string_rxspencer(String *s) {
 }
 #endif
 
+/* ------------------------------------------------------------
+ * is_generated_overload()
+ * Check if the function is an automatically generated
+ * overload created because a method has default parameters. 
+ * ------------------------------------------------------------ */
+int Swig_is_generated_overload(Node *n)
+{
+  Node *base_method = Getattr(n, "sym:overloaded");
+  Node *default_args = Getattr(n, "defaultargs");
+  return ((base_method != NULL) && (default_args != NULL) && (base_method == default_args));
+}
 
 /* -----------------------------------------------------------------------------
  * Swig_init()

Source/Swig/swig.h

@@ -300,8 +300,9 @@ extern int        ParmList_is_compactdefargs(ParmList *p);
 
   extern void Swig_init(void);
   extern void Swig_warn(const char *filename, int line, const char *msg);
-
+  
   extern int Swig_value_wrapper_mode(int mode);
+  extern int Swig_is_generated_overload(Node *n);
 
 
 #define WARNING(msg) Swig_warn(__FILE__,__LINE__,msg)