Preserve relative indentation when parsing Doxygen comments.

This is important to preserve the structure of the lists which appear
correctly in Python output without any additional effort if the indentation is
lost.

It is also makes the behaviour consistent for

	/**
	 *
	 *
	 */

comments and those without the asterisks in the middle lines, as now the
indentation is preserved in both cases while it was only preserved when the
asterisks were present previously.

Examples/test-suite/doxygen_misc_constructs.i

@@ -102,6 +102,20 @@
 
     };
 
+    /**
+        An example of a list in a documentation comment.
+
+            - The first item of the list.
+            - The second list item, on
+              several indented lines,
+              showing that the indentation
+              is preserved.
+            - And the final list item after it.
+
+        And this is not a list item any more.
+     */
+    void showList() { }
+
     #include "doxygen_misc_constructs.h"
     
 %}

Examples/test-suite/java/doxygen_misc_constructs_runme.java

@@ -117,6 +117,18 @@ public class doxygen_misc_constructs_runme {
     wantedComments.put("doxygen_misc_constructs.ClassWithNestedEnum.ENested.THREE",
     		" desc of three\n");
 
+    wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.showList()",
+"         An example of a list in a documentation comment.<br>\n" +
+" <br>\n" +
+"             - The first item of the list.<br>\n" +
+"             - The second list item, on<br>\n" +
+"               several indented lines,<br>\n" +
+"               showing that the indentation<br>\n" +
+"               is preserved.<br>\n" +
+"             - And the final list item after it.<br>\n" +
+" <br>\n" +
+"        And this is not a list item any more.\n" +
+    		"");
     wantedComments.put("doxygen_misc_constructs.doxygen_misc_constructs.isNoSpaceValidA()",
     		" This comment without space after '*' is valid in Doxygen.\n" +
     		"\n" +
@@ -182,4 +194,4 @@ public class doxygen_misc_constructs_runme {
     // and ask the parser to check comments for us
     System.exit(parser.check(wantedComments));
   }
-}
+}

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -64,6 +64,21 @@ commentVerifier.check(doxygen_misc_constructs.ClassWithNestedEnum.__doc__,
     """
 )
 
+commentVerifier.check(doxygen_misc_constructs.showList.__doc__,
+    r"""
+    An example of a list in a documentation comment.
+
+        - The first item of the list.
+        - The second list item, on
+          several indented lines,
+          showing that the indentation
+          is preserved.
+        - And the final list item after it.
+
+    And this is not a list item any more.
+    """
+)
+
 commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidA.__doc__,
     r"""
     This comment without space after '*' is valid in Doxygen.

Source/DoxygenTranslator/src/DoxygenParser.cpp

@@ -1338,19 +1338,23 @@ void DoxygenParser::tokenizeDoxygenComment(const std::string &doxygenComment,
     // line[pos] may be ' \t' or start of word, it there was no '*', '/' or '!'
     // at beginning of the line. Make sure it points to start of the first word
     // in the line.
-    size_t firstWordPos = line.find_first_not_of(" \t", pos);
-    if (firstWordPos == string::npos) {
-      m_tokenList.push_back(Token(END_LINE, "\n"));
-      continue;
-    }
+    if (isStartOfCommentLineCharFound) {
+      size_t firstWordPos = line.find_first_not_of(" \t", pos);
+      if (firstWordPos == string::npos) {
+        m_tokenList.push_back(Token(END_LINE, "\n"));
+        continue;
+      }
 
-    if (isStartOfCommentLineCharFound && firstWordPos > pos) {
-      m_tokenList.push_back(
-          Token(PLAINSTRING, line.substr(pos, firstWordPos - pos)));
+      if (firstWordPos > pos) {
+        m_tokenList.push_back(
+            Token(PLAINSTRING, line.substr(pos, firstWordPos - pos)));
+        pos = firstWordPos;
+      }
+    } else {
+        m_tokenList.push_back(
+            Token(PLAINSTRING, line.substr(0, pos)));
     }
 
-    pos = firstWordPos;
-
     while (pos != string::npos) {
       // find the end of the word
       size_t doxyCmdOrHtmlTagPos = line.find_first_of("\\@<>&\" \t", pos);