tests with escapes added, tests refactored - broken to smaller chunks

Doc/Manual/Doxygen.html

@@ -469,6 +469,10 @@ Here is the list of all Doxygen tags and the description of how they are transla
 <td>translated to @exception</td>
 </tr>
 <tr>
+<td>\f$, \f[, \f], \f{, \f}</td>
+<td>LateX formulas are left unchanged</td>
+</tr>
+<tr>
 <td>\if</td>
 <td>replaced with 'If: &lt;condition&gt; {'</td>
 </tr>
@@ -686,13 +690,6 @@ Here is the list of these tags:
 <td>\enum</td>
 <td>\example</td>
 <td>\extends</td>
-<td>\f$</td>
-</tr>
-<tr>
-<td>\f[</td>
-<td>\f]</td>
-<td>\f{</td>
-<td>\f}</td>
 </tr>
 <tr>
 <td>\file</td>

Examples/test-suite/doxygen_misc_constructs.h

@@ -26,24 +26,39 @@ void isNoSpaceValidC()
 
 
 /**
- * Backslash following\c word is valid doxygen command. Output contains
+ * Backslash following\c word is a valid doxygen command. Output contains
- * 'followingword' with word in 'code' font.
+ * 'followingword' with 'word' in 'code' font.
  */
 void backslashA()
 {}
 
+// Output of escaped symbols below in doxygen generated HTML:
+// Rendered: Escaped symbols: $ @ \ & < > # % " \. ::
+// HTML source: Escaped symbols: $ @ \ &amp; &lt; &gt; # % " \. :: 
+
 /**
- * Doxy command without trailing \cspace space is ignored. Standalone
+ * Doxy command without trailing \cspace space is ignored - nothing appears
- * \ and '\' get to output.  Commands not recognized by Doxygen \blah
+ * on output. Standalone \ and '\' get to output.
- * are ignored.  Backslashes in DOS paths d:\xyz\c\myfile and words
+ * Standalone @ and '@' get to output.
- * following them do not appear on output, we must quote them with
+ * Commands not recognized by Doxygen \blah @blah are ignored.
- * double quotes: "d:\xyz\c\myfile", single quotes do not help:
+ * 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", "@something". 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
+ * Escaped symbols:
+ * \$ \@ \\ \& \~ \< \> \# \% \" \. \::
  */
 void backslashB()
 {}
 
+/**
+ * Backslash e at end of \e line froze SWIG \e
+ * with old comment parser.
+ */
+void backslashC()
+{}
+
 /**
  *
  */

Examples/test-suite/doxygen_misc_constructs.i

@@ -31,7 +31,7 @@
      * Returns address of file line.
      *
      * @param fileName name of the file, where the source line is located
-	* @param line line number
+     * @param line line number
      * @param isGetSize if set, for every object location both address and size are returned
      *
      * @link Connection::getId() @endlink <br>

Examples/test-suite/doxygen_translate_all_tags.i

@@ -17,7 +17,6 @@
  * You were warned!
  *
  * \authors lots of them
- * 
  * \author Zubr
  * 
  * \b boldword
@@ -26,21 +25,22 @@
  * extended to many lines.
  *
  * \bug Not everything works right now...
- *
  * \c codeword
  * 
  * \callgraph
- *
  * \callergraph
- *
  * \category someCategory headerFile.h headerName
  *
  * \cite citationword
- * 
  * \class someClass headerFile.h headerName
- *
  * \code some test code \endcode
- * 
+ */
+int func01(int a)
+{
+}
+
+ 
+/** 
  * \cond SOMECONDITION
  * Some conditional comment
  * \endcond
@@ -63,7 +63,13 @@
  * 
  * \details This is very large
  * and detailed description of some thing
- *
+ */
+int func02(int a)
+{
+}
+
+ 
+/**
  * \dir /somePath/someFolder
  *
  * \dontinclude someFile.h
@@ -87,6 +93,13 @@
  *
  * \example someFile.txt
  * Some details on using the example
+ */
+int func03(int a)
+{
+}
+
+ 
+/**
  * 
  * \exception SuperError
  * 
@@ -115,7 +128,13 @@
  * \htmlonly
  * This will only appear in hmtl
  * \endhtmlonly
- *
+ */
+int func04(int a)
+{
+}
+
+ 
+/**
  * \if ANOTHERCONDITION
  *   First part of comment
  *   \if SECONDCONDITION
@@ -150,7 +169,13 @@
  *
  * \invariant Some text
  * describing invariant.
- *
+ */
+int func05(int a)
+{
+}
+
+ 
+/**
  * \interface someInterface someHeader.h "Header name"
  *
  * \latexonly
@@ -186,7 +211,13 @@
  * \mscfile mscFile.msc "The caption"
  *
  * \n \n \n
- * 
+ */
+int func06(int a)
+{
+}
+
+ 
+/**
  * \name someHeader.h
  *
  * \namespace someNamespace
@@ -221,7 +252,13 @@
  * \privatesection
  *
  * \property someVar
- *
+ */
+int func07(int a)
+{
+}
+
+ 
+/**
  * \protected
  *
  * \protectedsection
@@ -253,7 +290,13 @@
  * \returns may return
  * 
  * \retval someValue Some description
- *
+ */
+int func08(int a)
+{
+}
+
+ 
+/**
  * \rtfonly
  * This will only appear in RTF
  * \endrtfonly
@@ -294,7 +337,13 @@
  * \throw superException
  * 
  * \throws RuntimeError
- * 
+ */
+int func09(int a)
+{
+}
+
+ 
+/**
  * \todo Some very important task
  * 
  * \tparam b B is mentioned again...
@@ -331,7 +380,7 @@
  * 
  * And here goes simple text
  */
-int function(int a, float b)
+int func10(int a, float b)
 {
 }
 

Examples/test-suite/java/commentParser.java

@@ -5,97 +5,100 @@ import java.util.Map.Entry;
 import java.util.Iterator;
 
 public class commentParser {
-	static HashMap<String, String> parsedComments = new HashMap<String, String>();
+    static HashMap<String, String> parsedComments = new HashMap<String, String>();
 
-	public static boolean start(RootDoc root) {
+    public static boolean start(RootDoc root) {
 
-		/*
+        /*
-		 * This method is called by 'javadoc' and gets the whole parsed java
+         * This method is called by 'javadoc' and gets the whole parsed java
-		 * file, we get comments and store them
+         * file, we get comments and store them
-		 */
+         */
 
-		for (ClassDoc classDoc : root.classes()) {
+        for (ClassDoc classDoc : root.classes()) {
 
-			if (classDoc.getRawCommentText().length() > 0)
+            if (classDoc.getRawCommentText().length() > 0)
-				parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText());
+                parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText());
 
-			for (FieldDoc f : classDoc.enumConstants()) {
+            for (FieldDoc f : classDoc.enumConstants()) {
-				if (f.getRawCommentText().length() > 0)
+                if (f.getRawCommentText().length() > 0)
-					parsedComments.put(f.qualifiedName(), f.getRawCommentText());
+                    parsedComments.put(f.qualifiedName(), f.getRawCommentText());
-			}
+            }
-			for (FieldDoc f : classDoc.fields()) {
+            for (FieldDoc f : classDoc.fields()) {
-				if (f.getRawCommentText().length() > 0)
+                if (f.getRawCommentText().length() > 0)
-					parsedComments.put(f.qualifiedName(), f.getRawCommentText());
+                    parsedComments.put(f.qualifiedName(), f.getRawCommentText());
-			}
+            }
-			for (MethodDoc m : classDoc.methods()) {
+            for (MethodDoc m : classDoc.methods()) {
-				if (m.getRawCommentText().length() > 0)
+                if (m.getRawCommentText().length() > 0)
-					parsedComments.put(m.toString(), m.getRawCommentText());
+                    parsedComments.put(m.toString(), m.getRawCommentText());
-			}
+            }
-		}
+        }
-		return true;
+        return true;
-	}
+    }
 
-	public static int check(HashMap<String, String> wantedComments) {
+    
-		int errorCount=0;
+    public static int check(HashMap<String, String> wantedComments) {
-		Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator();
+        int errorCount=0;
+        Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator();
 
-		while (it.hasNext())
+        while (it.hasNext())
-		{
+        {
-			Entry<String, String> e = (Entry<String, String>) it.next();
+            Entry<String, String> e = (Entry<String, String>) it.next();
-			String actualStr = e.getValue();
+            String actualStr = e.getValue();
-			String wantedStr = wantedComments.get(e.getKey());
+            String wantedStr = wantedComments.get(e.getKey());
-			// this may be weird, but I don't know any more effective solution
+            // this may be weird, but I don't know any more effective solution
-			actualStr = actualStr.replace(" ", "");
+            actualStr = actualStr.replace(" ", "");
-			actualStr = actualStr.replace("\n", "");
+            actualStr = actualStr.replace("\n", "");
-			actualStr = actualStr.replace("\t", "");
+            actualStr = actualStr.replace("\t", "");
-			if (wantedStr != null) {
+            if (wantedStr != null) {
-				wantedStr = wantedStr.replace(" ", "");
+                wantedStr = wantedStr.replace(" ", "");
-				wantedStr = wantedStr.replace("\n", "");
+                wantedStr = wantedStr.replace("\n", "");
-				wantedStr = wantedStr.replace("\t", "");
+                wantedStr = wantedStr.replace("\t", "");
-			}
+            }
 
-			if (!actualStr.equals(wantedStr)) {
+            if (!actualStr.equals(wantedStr)) {
-				System.out.println("Documentation comments for " + e.getKey() + " does not match: ");
+                System.out.println("Documentation comments for " + e.getKey() + " do not match: ");
-				// here we print original strings, for nicer output
+                // here we print original strings, for nicer output
-				System.out.println("\texpected:"+wantedComments.get(e.getKey()));
+                System.out.println("\n\n---\nexpected:\n" + wantedComments.get(e.getKey()));
-				System.out.println("\tgot:\t"+e.getValue());
+                System.out.println("\n\n---\ngot:\n" + e.getValue());
-				errorCount++;
+                errorCount++;
-			}
+            }
-		}
+        }
 
-		if (parsedComments.size() < wantedComments.size()) {
+        if (parsedComments.size() < wantedComments.size()) {
-			System.out.println("Found " + (wantedComments.size()-parsedComments.size()) + " missed comment(s)!");
+            System.out.println("Found " + (wantedComments.size()-parsedComments.size()) + " missed comment(s)!");
-			errorCount++;
+            errorCount++;
-		}
+        }
 		
-		return errorCount;
+        return errorCount > 0 ? 1 : 0;
-	}
+    }
-	
+
-	public static void printCommentListForJavaSource() {
+    
-		Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator();
+    public static void printCommentListForJavaSource() {
-		while (it.hasNext())
+        Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator();
-		{
+        while (it.hasNext())
-			Entry<String, String> e = (Entry<String, String>) it.next();
+        {
-			String commentText = e.getValue();
+            Entry<String, String> e = (Entry<String, String>) it.next();
-			commentText = commentText.replace("\\", "\\\\");
+            String commentText = e.getValue();
-			commentText = commentText.replace("\"", "\\\"");
+            commentText = commentText.replace("\\", "\\\\");
-			commentText = commentText.replace("\n", "\\n\" +\n\t\t\"");
+            commentText = commentText.replace("\"", "\\\"");
-			System.out.format("wantedComments.put(\"%s\",\n\t\t\"%s\");\n", e.getKey(), commentText);
+            commentText = commentText.replace("\n", "\\n\" +\n\t\t\"");
-		}
+            System.out.format("wantedComments.put(\"%s\",\n\t\t\"%s\");\n", e.getKey(), commentText);
-	}
+        }
-	
+    }
-	public static void main(String argv[]) {
+
+    
+    public static void main(String argv[]) {
 		
-		if (argv.length<1) {
+        if (argv.length<1) {
-			System.out.format("Usage:\n\tcommentParsing <package to parse>\n");
+            System.out.format("Usage:\n\tcommentParsing <package to parse>\n");
-			System.exit(1);
+            System.exit(1);
-		}
+        }
 		
-		com.sun.tools.javadoc.Main.execute("The comment parser program",
+        com.sun.tools.javadoc.Main.execute("The comment parser program",
-				"commentParser", new String[]{"-quiet", argv[0]});
+                                           "commentParser", new String[]{"-quiet", argv[0]});
 		
-		// if we are run as standalone app, print the list of found comments as it would appear in java source
+        // if we are run as standalone app, print the list of found comments as it would appear in java source
 		
-		printCommentListForJavaSource();
+        printCommentListForJavaSource();
-	}
+    }
 }

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -25,20 +25,22 @@ public class doxygen_translate_all_tags_runme {
 
     HashMap<String, String> wantedComments = new HashMap<String, String>();
     
-    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.function(int, float)",
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func01(int)",
-    		" <i>Hello </i>\n" +
+    		" <i>Hello </i>\n\n\n\n\n\n" +
-    		" <li>some list item \n" +
+    		" <li>some list item</li>\n\n" +
-    		" </li>This is attention! \n" +
+    		" This is attention!\n" +
-    		" You were warned! \n" +
+    		" You were warned!\n" +
-    		" @author lots of them \n" +
+    		" @author lots of them\n" +
-    		" @author Zubr \n" +
+    		" @author Zubr\n\n" +
-    		" <b>boldword </b>\n" +
+    		" <b>boldword</b>\n\n" +
-    		" Some brief description, \n" +
+    		" Some brief description,\n" +
-    		" extended to many lines. \n" +
+    		" extended to many lines.\n\n" +
-    		" Not everything works right now... \n" +
+    		" Not everything works right now...\n" +
-    		" <code>codeword </code>\n" +
+    		" <code>codeword</code>\n\n\n\n\n\n" +
-    		" <i>citationword </i>\n" +
+    		" <i>citationword</i>\n" +
-    		" {@code some test code }\n" +
+                " {@code some test code }\n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func02(int)",
     		" Conditional comment: SOMECONDITION \n" +
     		" Some conditional comment \n" +
     		" End of conditional comment.\n" +
@@ -46,12 +48,18 @@ public class doxygen_translate_all_tags_runme {
     		" 1970 - 2012 \n" +
     		" @deprecated Now use another function \n" +
     		" This is very large \n" +
-    		" and detailed description of some thing \n" +
+    		" and detailed description of some thing \n");
-    		" <i>italicword </i>\n" +
+    
-    		" <i>emphazedWord </i>\n" +
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func03(int)",
-    		" @exception SuperError \n" +
+                       " <i>italicword </i>\n" +
-    		" This will only appear in hmtl \n" +
+    		" <i>emphazedWord </i>\n");
-    		" If: ANOTHERCONDITION {\n" +
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func04(int)",
+                       " @exception SuperError \n" +
+    		" This will only appear in hmtl \n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func05(int)",
+                       " If: ANOTHERCONDITION {\n" +
     		" First part of comment \n" +
     		" If: SECONDCONDITION {\n" +
     		" Nested condition text \n" +
@@ -69,16 +77,20 @@ public class doxygen_translate_all_tags_runme {
     		" }\n" +
     		" <img src=testImage.bmp alt=\"Hello, world!\" />\n" +
     		" Some text \n" +
-    		" describing invariant. \n" +
+    		" describing invariant. \n");
-    		" This will only appear in LATeX \n" +
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func06(int)",
+                       " This will only appear in LATeX \n" +
     		" <ul> \n" +
     		" <li>Some unordered list \n" +
     		" </li><li>With lots of items \n" +
     		" </li><li>lots of lots of items \n" +
     		" </li></ul> \n" +
     		" {@link someMember Some description follows }\n" +
-    		" This will only appear in man \n" +
+    		" This will only appear in man\n");
-    		" Note: Here \n" +
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int)",
+                       " Note: Here \n" +
     		" is the note! \n" +
     		" This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" +
     		" <code>someword </code>\n" +
@@ -87,21 +99,27 @@ public class doxygen_translate_all_tags_runme {
     		" The paragraph text. \n" +
     		" Maybe even multiline \n" +
     		" </p>\n" +
-    		" @param a the first param \n" +
+                " @param a the first param\n");
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func08(int)",
     		" Remarks: Some remark text \n" +
     		" Remarks: Another remarks section \n" +
     		" @return Whatever \n" +
     		" @return it \n" +
-    		" @return may return \n" +
+    		" @return may return \n");
-    		" This will only appear in RTF \n" +
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func09(int)",
+                       " This will only appear in RTF \n" +
     		" @see someOtherMethod \n" +
     		" @see function \n" +
     		" Same as \n" +
     		" brief description \n" +
     		" @since version 0.0.0.1 \n" +
     		" @throws superException \n" +
-    		" @throws RuntimeError \n" +
+    		" @throws RuntimeError \n");
-    		" TODO: Some very important task \n" +
+    
+    wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func10(int, float)",
+                       " TODO: Some very important task \n" +
     		" @param b B is mentioned again... \n" +
     		" {@literal \n" +
     		"very long \n" +