Implemented support for default args - overloaded functions, optional feature 1 in my project plan. Extended testcase.

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen@13483 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Examples/test-suite/doxygen_basic_translate.i

@@ -61,6 +61,7 @@ int function4()
 
 /**
  * Test for default args
+ * @param a Some parameter, default is 42
  */
 int function5(int a=42)
 {

Examples/test-suite/java/doxygen_basic_translate_runme.java

@@ -63,6 +63,11 @@ public class doxygen_basic_translate_runme {
     		" \n" +
     		"");
     wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function5(int)",
+    		" Test for default args \n" +
+    		" @param a Some parameter, default is 42" +
+    		" \n" +
+    		"");
+    wantedComments.put("doxygen_basic_translate.doxygen_basic_translate.function5()",
     		" Test for default args \n" +
     		" \n" +
     		"");

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -58,5 +58,7 @@ check(doxygen_basic_translate.function4.__doc__, ''
 '  }'
 )
 check(doxygen_basic_translate.function5.__doc__, ''
-'  Test for default args'
+'  Test for default args \n'
+'  Arguments: \n'
+'  a (int) -- Some parameter, default is 42\n'
 )

Source/CParse/parser.y

@@ -190,6 +190,7 @@ static Node *copy_node(Node *n) {
 }
 
 static void set_comment(Node *n, String *comment) {
+  String *name;
   Parm *p;
   if (!n || !comment)
     return;
@@ -206,6 +207,16 @@ static void set_comment(Node *n, String *comment) {
       p=nextSibling(p);
     }
   }
+  
+  /* Append same comment to every generated overload */
+  name = Getattr(n, "name");
+  if (!name)
+    return;
+  n = nextSibling(n);
+  while (n && Getattr(n, "name") && Strcmp(Getattr(n, "name"), name) == 0) {
+    Setattr(n, "DoxygenComment", comment);
+    n = nextSibling(n);
+  }
 }
 
 /* -----------------------------------------------------------------------------
@@ -1586,10 +1597,6 @@ static void default_arguments(Node *n) {
           if (throws) Setattr(new_function,"throws",pl);
 	  Delete(pl);
         }
-	
-	/* copy doxygen comments if found */
-	if(Getattr(function,"DoxygenComment"))
-	  Setattr(new_function,"DoxygenComment",Getattr(function,"DoxygenComment"));
 
         /* copy specific attributes for global (or in a namespace) template functions - these are not templated class methods */
         if (strcmp(cntype,"template") == 0) {

Source/DoxygenTranslator/src/JavaDocConverter.cpp

@@ -66,8 +66,8 @@ void JavaDocConverter::fillStaticTables() {
   tagHandlers["deprecated"] = make_pair(&JavaDocConverter::handleTagSame, "");
   tagHandlers["exception"] = make_pair(&JavaDocConverter::handleTagSame, "");
   tagHandlers["package"] = make_pair(&JavaDocConverter::handleTagSame, "");
-  tagHandlers["param"] = make_pair(&JavaDocConverter::handleTagSame, "");
-  tagHandlers["tparam"] = make_pair(&JavaDocConverter::handleTagSame, "param");
+  tagHandlers["param"] = make_pair(&JavaDocConverter::handleTagParam, "");
+  tagHandlers["tparam"] = make_pair(&JavaDocConverter::handleTagParam, "");
   tagHandlers["result"] = make_pair(&JavaDocConverter::handleTagSame, "return");
   tagHandlers["return"] = make_pair(&JavaDocConverter::handleTagSame, "");
   tagHandlers["returns"] = make_pair(&JavaDocConverter::handleTagSame, "return");
@@ -151,6 +151,23 @@ std::string JavaDocConverter::formatCommand(std::string unformattedLine, int ind
   return formattedLines;
 }
 
+bool JavaDocConverter::paramExists(std::string param) {
+  ParmList *plist = CopyParmList(Getattr(currentNode, "parms"));
+  Parm *p = NULL;
+  for (p = plist; p;) {
+    if (Char(Getattr(p, "name")) == param)
+      return true;
+    /*
+     * doesn't seem to work always: in some cases (especially for 'self' parameters)
+     * tmap:in is present, but tmap:in:next is not and so this code skips all the parameters
+     */
+    //p = Getattr(p, "tmap:in") ? Getattr(p, "tmap:in:next") : nextSibling(p);
+    p = nextSibling(p);
+  }
+  Delete(plist);
+  return false;
+}
+
 std::string JavaDocConverter::translateSubtree(DoxygenEntity & doxygenEntity) {
   std::string translatedComment;
   
@@ -250,12 +267,26 @@ void JavaDocConverter::handleTagImage(DoxygenEntity& tag, std::string& translate
 void JavaDocConverter::handleTagPar(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
   std::string dummy;
   translatedComment += "<p";
-  if (tag.entityList.size())
+  if (tag.entityList.size()) {
     translatedComment += " alt=\"" + tag.entityList.begin()->data + "\"";
-  translatedComment += ">";
+    translatedComment += ">";
+    tag.entityList.pop_front();
+    handleParagraph(tag, translatedComment, dummy);
+  }
+  translatedComment += "</p>";
+}
+
+void JavaDocConverter::handleTagParam(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
+  std::string dummy;
+  if (!tag.entityList.size())
+    return;
+  if (!paramExists(tag.entityList.begin()->data))
+    return;
+
+  translatedComment += "@param ";
+  translatedComment += tag.entityList.begin()->data + " ";
   tag.entityList.pop_front();
   handleParagraph(tag, translatedComment, dummy);
-  translatedComment += "</p>";
 }
 
 String *JavaDocConverter::makeDocumentation(Node *node) {
@@ -278,6 +309,9 @@ String *JavaDocConverter::makeDocumentation(Node *node) {
 
   std::string javaDocString = "/**\n * ";
 
+  // store the current node
+  // (currently just to handle params)
+  currentNode = node;
   for (std::list < DoxygenEntity >::iterator entityIterator = entityList.begin(); entityIterator != entityList.end();) {
     translateEntity(*entityIterator, javaDocString);
     entityIterator++;

Source/DoxygenTranslator/src/JavaDocConverter.h

@@ -85,12 +85,19 @@ protected:
    * Insert <p alt='title'>...</p>
    */
   void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
+  /*
+   * Insert @param command, if it is really a function param
+   */
+  void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
 
 
 private:
+  Node *currentNode;
   // this contains the handler pointer and one string argument
   static std::map<std::string, std::pair<tagHandler, std::string> > tagHandlers;
   void fillStaticTables();
+
+  bool paramExists(std::string param);
 };
 
 #endif