fixed handling of /******/ comments, added tests for backslash handling, which fail

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

Examples/test-suite/doxygen_misc_constructs.h

@@ -0,0 +1,52 @@
+/*
+ * This file contains comments which demonstrate details about Doxygen processing,
+ * so they can be emulated in SWIG doxy comment translation
+ */
+
+
+
+/**This comment without space after '*' is valid in Doxygen.
+ *
+ */
+void isNoSpaceValidA()
+{}
+
+/**.This comment without space after '*' is valid in Doxygen.
+ *
+ */
+void isNoSpaceValidB()
+{}
+
+
+/***This is not Doxygen comment.
+ *
+ */
+void isNoSpaceValidC()
+{}
+
+
+/**
+ * Backslash following\c word is valid doxygen command. Output contains
+ * 'followingword' with word in 'code' font.
+ */
+void backslashA()
+{}
+
+/**
+ * Doxy command without trailing \cspace space is ignored. Standalone
+ * \ and '\' get to output.  Commands not recognized by Doxygen \blah
+ * are ignored.  Backslashes in DOS paths d:\xyz\c\myfile and words
+ * following them do not appear on output, we must quote them with
+ * double quotes: "d:\xyz\c\myfile", single quotes do not help:
+ * 'd:\xyz\c\myfile'. Escaping works: d:\\xyz\\c\\myfile. Unix
+ * paths of course have no such problems: /xyz/c/myfile
+ */
+void backslashB()
+{}
+
+/**
+ *
+ */
+void htmlTags()
+{}
+

Examples/test-suite/doxygen_misc_constructs.i

@@ -38,9 +38,7 @@
      */
     void getAddress(int &fileName, 
                     int line,     
-                                  bool isGetSize = false)
+                    bool isGetSize = false) {}
-    {
-    }
 
     // The first comment must be ignored.
     /** 
@@ -74,19 +72,20 @@
      * instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags
      * may be specified.
      */
-    int waitTime(long waitTime)
+    int waitTime(long waitTime) {return 33;}
-    {
-    }
 
 
     // Line with tag \ingroup must not appear in translated comment:
     /** \ingroup icFacade
      *
-     * This class manages connection.
+     * This function returns connection id.
      */
-    int getConnection()
+    int getConnection() {return 3;}
-    {
+
-    }
+    // the follwing must produce no comment in wrapper
+    /*******************************************************************/
+    char getFirstLetter() {return 'a';}
+
     
     /**
      * Class description.
@@ -94,7 +93,7 @@
     class ClassWithNestedEnum {
     public:
         /**
-         * Enum description.b
+         * Enum description.
          */
         typedef enum {ONE,  ///< desc of one
                       TWO,  ///< desc of two
@@ -102,4 +101,8 @@
         } ENested;
 
     };
+
+    #include "doxygen_misc_constructs.h"
+    
 %}
+    %include "doxygen_misc_constructs.h"

Examples/test-suite/java/doxygen_misc_constructs_runme.java

@@ -28,7 +28,7 @@ public class doxygen_misc_constructs_runme {
     wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getConnection()",
     		" \n" +
     		" \n" +
-    		" This class manages connection. \n" +
+    		" This function returns connection id. \n" +
     		" \n" +
     		"");
     wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.getAddress(doxygen_misc_constructs.SWIGTYPE_p_int, int)",
@@ -119,6 +119,32 @@ public class doxygen_misc_constructs_runme {
     		" desc of three\n" +
     		" \n");
 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidA()",
+    		" This comment without space after '*' is valid in Doxygen. \n" +
+    		" \n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidB()",
+    		" .This comment without space after '*' is valid in Doxygen. \n" +
+    		" \n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashA()",
+    		" Backslash following<code>word</code> is valid doxygen command. Output contains \n" +
+    		" 'followingword' with word in 'code' font. \n" +
+    		" \n" +
+    		"");
+ 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.backslashB()",
+                       " Doxy command without trailing cspace space is ignored. Standalone \n" +
+                       " \\ and '\\' get to output. Commands not recognized by Doxygen \n" +
+                       " are ignored. Backslashes in DOS paths d: and words \n" +
+                       " following them do not appear on output, we must quote them with \n" +
+                       " double quotes: \"d:\\xyz\\c\\myfile\", single quotes do not help: \n" +
+                       " 'd: '. Escaping works: d:\\xyz\\c\\myfile. Unix \n" +
+                       " paths of course have no such problems: /xyz/c/myfile \n" +
+    		" \n");
+ 
     // and ask the parser to check comments for us
     System.exit(parser.check(wantedComments));
   }

Source/CParse/cscanner.c

@@ -350,6 +350,8 @@ static int yylook(void) {
 	  }
 	  if (strncmp(loc, "/**", 3) == 0 || strncmp(loc, "///", 3) == 0||strncmp(loc, "/*!", 3) == 0||strncmp(loc, "//!", 3) == 0) {
 	    /* printf("Doxygen Comment: %s lines %d-%d [%s]\n", Char(Scanner_file(scan)), Scanner_start_line(scan), Scanner_line(scan), loc); */
+	    /* ignore comments like / * * * and / * * /,  which are also ignored by Doxygen */
+	    if (loc[3] != '*'  &&  loc[3] != '/') {
 	      yylval.str =  NewString(loc);
 	      Setline(yylval.str, Scanner_start_line(scan));
 	      Setfile(yylval.str, Scanner_file(scan));
@@ -357,6 +359,7 @@ static int yylook(void) {
 	    }
 	  }
 	}
+      }
       break;
     case SWIG_TOKEN_ENDLINE:
       break;

Source/DoxygenTranslator/src/JavaDocConverter.cpp

@@ -549,6 +549,10 @@ std::string JavaDocConverter::indentAndInsertAsterisks(const string &doc) {
     }
   }
 
+  if (indent == 0) { // we can't indent the first line less than 0
+    indent = 1;
+  }
+
   // Create the first line of Javadoc comment.
   string indentStr(indent - 1, ' ');
   string translatedStr = indentStr + "/**";