Fix generated Python code for Doxygen comments with triple quotes

In addition to the changes in the previous commit, also avoid syntax
errors in the generated Python docstrings by splitting them into several
parts if there are 3 quotes in a row in the input, as it's impossible to
have them inside triple-quoted strings, generally speaking (i.e. if
there are occurrences of both """ and ''' inside the string).

Author: vadz

Examples/test-suite/doxygen_misc_constructs.h

@@ -94,3 +94,9 @@ 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

@@ -188,6 +188,10 @@ public static void main(String argv[])
     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

@@ -135,3 +135,9 @@
 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

@@ -1599,6 +1599,16 @@ class PYTHON:public Language {
 
     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, useSingleQuotes ? "'''" : "\"\"\"");
     Delete(docstr);