diff options
author | Marko Klopcic <markok3.14@gmail.com> | 2013-01-10 22:26:50 +0100 |
---|---|---|
committer | Marko Klopcic <markok3.14@gmail.com> | 2013-01-10 22:26:50 +0100 |
commit | 20cc685e8aa64c0b802dcb3f7e2efc67498fb1ea (patch) | |
tree | 6f217b5f31876b72cc8e5f135b0b15056d25fef5 | |
parent | a9ef35bc66d90e44694618451a7f464a9e67fa80 (diff) | |
download | swig-20cc685e8aa64c0b802dcb3f7e2efc67498fb1ea.tar.gz |
tests with escapes added, tests refactored - broken to smaller chunks
-rw-r--r-- | Doc/Manual/Doxygen.html | 11 | ||||
-rw-r--r-- | Examples/test-suite/doxygen_misc_constructs.h | 29 | ||||
-rw-r--r-- | Examples/test-suite/doxygen_misc_constructs.i | 2 | ||||
-rw-r--r-- | Examples/test-suite/doxygen_translate_all_tags.i | 79 | ||||
-rw-r--r-- | Examples/test-suite/java/commentParser.java | 161 | ||||
-rw-r--r-- | Examples/test-suite/java/doxygen_translate_all_tags_runme.java | 76 |
6 files changed, 220 insertions, 138 deletions
diff --git a/Doc/Manual/Doxygen.html b/Doc/Manual/Doxygen.html index d71c6dcba..bc68ed15c 100644 --- a/Doc/Manual/Doxygen.html +++ b/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: <condition> {'</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> diff --git a/Examples/test-suite/doxygen_misc_constructs.h b/Examples/test-suite/doxygen_misc_constructs.h index 813e6ddcd..e5d317fc2 100644 --- a/Examples/test-suite/doxygen_misc_constructs.h +++ b/Examples/test-suite/doxygen_misc_constructs.h @@ -26,25 +26,40 @@ void isNoSpaceValidC() /**
- * Backslash following\c word is valid doxygen command. Output contains
- * 'followingword' with word in 'code' font.
+ * Backslash following\c word is a valid doxygen command. Output contains
+ * 'followingword' with 'word' in 'code' font.
*/
void backslashA()
{}
+// Output of escaped symbols below in doxygen generated HTML:
+// Rendered: Escaped symbols: $ @ \ & < > # % " \. ::
+// HTML source: Escaped symbols: $ @ \ & < > # % " \. ::
+
/**
- * 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:
+ * Doxy command without trailing \cspace space is ignored - nothing appears
+ * on output. Standalone \ and '\' get to output.
+ * Standalone @ and '@' get to output.
+ * Commands not recognized by Doxygen \blah @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", "@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()
+{}
+
+/**
*
*/
void htmlTags()
diff --git a/Examples/test-suite/doxygen_misc_constructs.i b/Examples/test-suite/doxygen_misc_constructs.i index 447e6b24e..0eee8aa9d 100644 --- a/Examples/test-suite/doxygen_misc_constructs.i +++ b/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>
diff --git a/Examples/test-suite/doxygen_translate_all_tags.i b/Examples/test-suite/doxygen_translate_all_tags.i index cb3332179..f780b643a 100644 --- a/Examples/test-suite/doxygen_translate_all_tags.i +++ b/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) { } diff --git a/Examples/test-suite/java/commentParser.java b/Examples/test-suite/java/commentParser.java index 94beb8c2f..581a862c8 100644 --- a/Examples/test-suite/java/commentParser.java +++ 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 - * file, we get comments and store them - */ + /* + * This method is called by 'javadoc' and gets the whole parsed java + * file, we get comments and store them + */ - for (ClassDoc classDoc : root.classes()) { + for (ClassDoc classDoc : root.classes()) { - if (classDoc.getRawCommentText().length() > 0) - parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText()); + if (classDoc.getRawCommentText().length() > 0) + parsedComments.put(classDoc.qualifiedName(), classDoc.getRawCommentText()); - for (FieldDoc f : classDoc.enumConstants()) { - if (f.getRawCommentText().length() > 0) - parsedComments.put(f.qualifiedName(), f.getRawCommentText()); - } - for (FieldDoc f : classDoc.fields()) { - if (f.getRawCommentText().length() > 0) - parsedComments.put(f.qualifiedName(), f.getRawCommentText()); - } - for (MethodDoc m : classDoc.methods()) { - if (m.getRawCommentText().length() > 0) - parsedComments.put(m.toString(), m.getRawCommentText()); - } - } - return true; - } + for (FieldDoc f : classDoc.enumConstants()) { + if (f.getRawCommentText().length() > 0) + parsedComments.put(f.qualifiedName(), f.getRawCommentText()); + } + for (FieldDoc f : classDoc.fields()) { + if (f.getRawCommentText().length() > 0) + parsedComments.put(f.qualifiedName(), f.getRawCommentText()); + } + for (MethodDoc m : classDoc.methods()) { + if (m.getRawCommentText().length() > 0) + parsedComments.put(m.toString(), m.getRawCommentText()); + } + } + return true; + } - public static int check(HashMap<String, String> wantedComments) { - int errorCount=0; - Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator(); + + public static int check(HashMap<String, String> wantedComments) { + int errorCount=0; + Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator(); - while (it.hasNext()) - { - Entry<String, String> e = (Entry<String, String>) it.next(); - String actualStr = e.getValue(); - String wantedStr = wantedComments.get(e.getKey()); - // this may be weird, but I don't know any more effective solution - actualStr = actualStr.replace(" ", ""); - actualStr = actualStr.replace("\n", ""); - actualStr = actualStr.replace("\t", ""); - if (wantedStr != null) { - wantedStr = wantedStr.replace(" ", ""); - wantedStr = wantedStr.replace("\n", ""); - wantedStr = wantedStr.replace("\t", ""); - } + while (it.hasNext()) + { + Entry<String, String> e = (Entry<String, String>) it.next(); + String actualStr = e.getValue(); + String wantedStr = wantedComments.get(e.getKey()); + // this may be weird, but I don't know any more effective solution + actualStr = actualStr.replace(" ", ""); + actualStr = actualStr.replace("\n", ""); + actualStr = actualStr.replace("\t", ""); + if (wantedStr != null) { + wantedStr = wantedStr.replace(" ", ""); + wantedStr = wantedStr.replace("\n", ""); + wantedStr = wantedStr.replace("\t", ""); + } - if (!actualStr.equals(wantedStr)) { - System.out.println("Documentation comments for " + e.getKey() + " does not match: "); - // here we print original strings, for nicer output - System.out.println("\texpected:"+wantedComments.get(e.getKey())); - System.out.println("\tgot:\t"+e.getValue()); - errorCount++; - } - } + if (!actualStr.equals(wantedStr)) { + System.out.println("Documentation comments for " + e.getKey() + " do not match: "); + // here we print original strings, for nicer output + System.out.println("\n\n---\nexpected:\n" + wantedComments.get(e.getKey())); + System.out.println("\n\n---\ngot:\n" + e.getValue()); + errorCount++; + } + } - if (parsedComments.size() < wantedComments.size()) { - System.out.println("Found " + (wantedComments.size()-parsedComments.size()) + " missed comment(s)!"); - errorCount++; - } + if (parsedComments.size() < wantedComments.size()) { + System.out.println("Found " + (wantedComments.size()-parsedComments.size()) + " missed comment(s)!"); + errorCount++; + } - return errorCount; - } - - public static void printCommentListForJavaSource() { - Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator(); - while (it.hasNext()) - { - Entry<String, String> e = (Entry<String, String>) it.next(); - String commentText = e.getValue(); - commentText = commentText.replace("\\", "\\\\"); - commentText = commentText.replace("\"", "\\\""); - 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[]) { + return errorCount > 0 ? 1 : 0; + } + + + public static void printCommentListForJavaSource() { + Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator(); + while (it.hasNext()) + { + Entry<String, String> e = (Entry<String, String>) it.next(); + String commentText = e.getValue(); + commentText = commentText.replace("\\", "\\\\"); + commentText = commentText.replace("\"", "\\\""); + 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[]) { - if (argv.length<1) { - System.out.format("Usage:\n\tcommentParsing <package to parse>\n"); - System.exit(1); - } + if (argv.length<1) { + System.out.format("Usage:\n\tcommentParsing <package to parse>\n"); + System.exit(1); + } - com.sun.tools.javadoc.Main.execute("The comment parser program", - "commentParser", new String[]{"-quiet", argv[0]}); + com.sun.tools.javadoc.Main.execute("The comment parser program", + "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(); + } } diff --git a/Examples/test-suite/java/doxygen_translate_all_tags_runme.java b/Examples/test-suite/java/doxygen_translate_all_tags_runme.java index 6db1f6686..9d9cec2b7 100644 --- a/Examples/test-suite/java/doxygen_translate_all_tags_runme.java +++ b/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)", - " <i>Hello </i>\n" + - " <li>some list item \n" + - " </li>This is attention! \n" + - " You were warned! \n" + - " @author lots of them \n" + - " @author Zubr \n" + - " <b>boldword </b>\n" + - " Some brief description, \n" + - " extended to many lines. \n" + - " Not everything works right now... \n" + - " <code>codeword </code>\n" + - " <i>citationword </i>\n" + - " {@code some test code }\n" + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func01(int)", + " <i>Hello </i>\n\n\n\n\n\n" + + " <li>some list item</li>\n\n" + + " This is attention!\n" + + " You were warned!\n" + + " @author lots of them\n" + + " @author Zubr\n\n" + + " <b>boldword</b>\n\n" + + " Some brief description,\n" + + " extended to many lines.\n\n" + + " Not everything works right now...\n" + + " <code>codeword</code>\n\n\n\n\n\n" + + " <i>citationword</i>\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" + - " <i>italicword </i>\n" + - " <i>emphazedWord </i>\n" + - " @exception SuperError \n" + - " This will only appear in hmtl \n" + - " If: ANOTHERCONDITION {\n" + + " and detailed description of some thing \n"); + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func03(int)", + " <i>italicword </i>\n" + + " <i>emphazedWord </i>\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" + - " This will only appear in LATeX \n" + + " describing invariant. \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" + - " Note: Here \n" + + " This will only appear in man\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" + - " This will only appear in RTF \n" + + " @return may return \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" + - " TODO: Some very important task \n" + + " @throws RuntimeError \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" + |