From 20cc685e8aa64c0b802dcb3f7e2efc67498fb1ea Mon Sep 17 00:00:00 2001 From: Marko Klopcic Date: Thu, 10 Jan 2013 22:26:50 +0100 Subject: tests with escapes added, tests refactored - broken to smaller chunks --- Doc/Manual/Doxygen.html | 11 +- Examples/test-suite/doxygen_misc_constructs.h | 29 +++- Examples/test-suite/doxygen_misc_constructs.i | 2 +- Examples/test-suite/doxygen_translate_all_tags.i | 79 ++++++++-- Examples/test-suite/java/commentParser.java | 161 +++++++++++---------- .../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 translated to @exception +\f$, \f[, \f], \f{, \f} +LateX formulas are left unchanged + + \if replaced with 'If: <condition> {' @@ -686,13 +690,6 @@ Here is the list of these tags: \enum \example \extends -\f$ - - -\f[ -\f] -\f{ -\f} \file 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,24 +26,39 @@ 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() +{} + /** * */ 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
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 parsedComments = new HashMap(); + static HashMap parsedComments = new HashMap(); - 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 wantedComments) { - int errorCount=0; - Iterator< Entry > it = parsedComments.entrySet().iterator(); + + public static int check(HashMap wantedComments) { + int errorCount=0; + Iterator< Entry > it = parsedComments.entrySet().iterator(); - while (it.hasNext()) - { - Entry e = (Entry) 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 e = (Entry) 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 > it = parsedComments.entrySet().iterator(); - while (it.hasNext()) - { - Entry e = (Entry) 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 > it = parsedComments.entrySet().iterator(); + while (it.hasNext()) + { + Entry e = (Entry) 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 \n"); - System.exit(1); - } + if (argv.length<1) { + System.out.format("Usage:\n\tcommentParsing \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 wantedComments = new HashMap(); - wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.function(int, float)", - " Hello \n" + - "
  • some list item \n" + - "
    • This is attention! \n" + - " You were warned! \n" + - " @author lots of them \n" + - " @author Zubr \n" + - " boldword \n" + - " Some brief description, \n" + - " extended to many lines. \n" + - " Not everything works right now... \n" + - " codeword \n" + - " citationword \n" + - " {@code some test code }\n" + + wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func01(int)", + " Hello \n\n\n\n\n\n" + + "
  • some list item
    • \n\n" + + " This is attention!\n" + + " You were warned!\n" + + " @author lots of them\n" + + " @author Zubr\n\n" + + " boldword\n\n" + + " Some brief description,\n" + + " extended to many lines.\n\n" + + " Not everything works right now...\n" + + " codeword\n\n\n\n\n\n" + + " citationword\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" + - " italicword \n" + - " emphazedWord \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)", + " italicword \n" + + " emphazedWord \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" + " \"Hello,\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" + "
      \n" + "
    • Some unordered list \n" + "
    • With lots of items \n" + "
    • lots of lots of items \n" + "
    \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" + " someword \n" + @@ -87,21 +99,27 @@ public class doxygen_translate_all_tags_runme { " The paragraph text. \n" + " Maybe even multiline \n" + "

    \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" + -- cgit v1.2.1