Merge branch 'python-doxygen-quotes'

* python-doxygen-quotes:
  Fix generated Python code for Doxygen comments with triple quotes
  Fix generated Python code for Doxygen comments ending with quote

Author: wsfulton

Examples/test-suite/doxygen_misc_constructs.h

@@ -91,4 +91,12 @@ void backslashC()
 void cycle(int id, char *fileName)
 {}
 
+/// This doc comment ends with a quote: "and that's ok"
+void doc_ends_with_quote() {}
 
+/**
+    This comment contains embedded triple-quoted string:
+
+        """How quaint"""
+ */
+void doc_with_triple_quotes() {}

Examples/test-suite/java/doxygen_misc_constructs_runme.java

@@ -185,6 +185,12 @@ public static void main(String argv[])
                 "\n" +
                 " @param fileName name of the log file\n");
 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.doc_ends_with_quote()",
+            "This doc comment ends with a quote: \"and that's ok\"");
+
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.doc_with_triple_quotes()",
+            "This comment contains embedded triple-quoted string:\n" +
+            "\"\"\"How quaint\"\"\"");
 
     // and ask the parser to check comments for us
     System.exit(CommentParser.check(wantedComments));

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -131,3 +131,13 @@
 :type fileName: string
 :param fileName: name of the log file"""
 );
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.doc_ends_with_quote),
+    r'''This doc comment ends with a quote: "and that's ok"'''
+);
+
+comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.doc_with_triple_quotes),
+    r'''This comment contains embedded triple-quoted string:
+
+    """How quaint"""'''
+);

Source/Modules/python.cxx

@@ -1571,7 +1571,8 @@ class PYTHON:public Language {
 
   String *docstring(Node *n, autodoc_t ad_type, const String *indent, bool low_level = false) {
     String *docstr = build_combined_docstring(n, ad_type, indent, low_level);
-    if (!Len(docstr))
+    const int len = Len(docstr);
+    if (!len)
       return docstr;
 
     // Notice that all comments are created as raw strings (prefix "r"),
@@ -1584,9 +1585,32 @@ class PYTHON:public Language {
     // escape '\x'. '\' may additionally appear in verbatim or htmlonly sections
     // of doxygen doc, Latex expressions, ...
     String *doc = NewString("");
-    Append(doc, "r\"\"\"");
+
+    // Determine which kind of quotes to use as delimiters: for single line
+    // strings we can avoid problems with having a quote as the last character
+    // of the docstring by using different kind of quotes as delimiters. For
+    // multi-line strings this problem doesn't arise, as we always have a new
+    // line or spaces at the end of it, but it still does no harm to do it for
+    // them too.
+    //
+    // Note: we use double quotes by default, i.e. if there is no reason to
+    // prefer using single ones, for consistency with the older SWIG versions.
+    const bool useSingleQuotes = (Char(docstr))[len - 1] == '"';
+
+    Append(doc, useSingleQuotes ? "r'''" : "r\"\"\"");
+
+    // We also need to avoid having triple quotes of whichever type we use, as
+    // this would break Python doc string syntax too. Unfortunately there is no
+    // way to have triple quotes inside of raw-triple-quoted string, so we have
+    // to break the string in parts and rely on concatenation of the adjacent
+    // string literals.
+    if (useSingleQuotes)
+      Replaceall(docstr, "'''", "''' \"'''\" '''");
+    else
+      Replaceall(docstr, "\"\"\"", "\"\"\" '\"\"\"' \"\"\"");
+
     Append(doc, docstr);
-    Append(doc, "\"\"\"");
+    Append(doc, useSingleQuotes ? "'''" : "\"\"\"");
     Delete(docstr);
 
     return doc;