[clang] [Clang][Comments] Support for parsing headers in Doxygen \par commands (PR #91100)

[via cfe-commits]

================
@@ -149,6 +149,63 @@ class TextTokenRetokenizer {
     addToken();
   }
 
+  /// Check if this line starts with @par or \par
+  bool startsWithParCommand() {
+    unsigned Offset = 1;
+
+    /// Skip all whitespace characters at the beginning.
+    /// This needs to backtrack because Pos has already advanced past the
+    /// actual \par or @par command by the time this function is called.
+    while (isWhitespace(*(Pos.BufferPtr - Offset)))
+      Offset++;
----------------
hdoc wrote:

The check is needed because Doxygen interprets the `@par` command differently if there is text on the same line or not.

If there is text on the same line, such as in Example 1 below, then the text is interpreted to be the paragraph heading, and that heading is stored as an argument for the comment. If there is no text on the same line, i.e. `@par` is alone on the line as in Example 2, then the paragraph is interpreted to have no heading.

```
/// @par I am a paragraph heading
void example1() {}

/// @par 
/// I am a paragraph with no heading
void example2() {}
```

To be able to correctly parse the paragraph heading, the lexer needs to go and check where the `@par` actually is, because if it's on the same line as some text we need to slurp that text and put it into the Arg for the comment. This code implements the functionality for this check by backtracking until it sees whitespace, and then checking whether the text immediately preceding that whitespace is a `@par` command or not.

All that being said, your feedback is helpful and I did find a small bug while re-checking this code. `Offset` should be used, otherwise the code has an implicit assumption that there is only one `char` of whitespace between the text and the `@par`. I've fixed that in the latest commit. Thank you for pointing that out :)

https://github.com/llvm/llvm-project/pull/91100