[clang-tools-extra] [clang-doc] Add regression test for test comments in macros (PR #132510)

[Paul Kirth via cfe-commits]

================
@@ -0,0 +1,34 @@
+// Fixes #59819. The underlying problem was fixed in https://reviews.llvm.org/D142560, but this patch adds a proper regression test.
+// RUN: rm -rf %t && mkdir -p %t
+// RUN: clang-doc --format=md --doxygen --output=%t --executor=standalone %s
+// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MYCLASS-LINE
+// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MYCLASS
+// RUN: clang-doc --format=html --doxygen --output=%t --executor=standalone %s
+// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.html --check-prefix=HTML-MYCLASS-LINE
+// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.html --check-prefix=HTML-MYCLASS
+
+#define DECLARE_METHODS                                           \
+    /**   							  \
+     * @brief Declare a method to calculate the sum of two numbers\
+     */                                                           \
+    int Add(int a, int b)                                         \
+    {                                                             \
+        return a + b;                                             \
+    }
+
+// MD-MYCLASS: ### Add
+// MD-MYCLASS: *public int Add(int a, int b)*
+// MD-MYCLASS: **brief** Declare a method to calculate the sum of two numbers
+
+// HTML-MYCLASS: <p>public int Add(int a, int b)</p>
+// HTML-MYCLASS: <div>brief</div>
+// HTML-MYCLASS: <p> Declare a method to calculate the sum of two numbers</p>
----------------
ilovepi wrote:

https://llvm.org/docs/CommandGuide/FileCheck.html#the-check-next-directive has information on how the `-NEXT` suffix works.

You use it the following way.

```
MYCHECK: match first line
MYCHECK-NEXT: match has to be on following line after the previous MYCHECK
MYCHECK: match something (potentially) far away
MYCHECK-NEXT: match has to be on the following line after the previous MYCHECK
```

What this allows you do do is be certain you're matching the correct part of the output, and that you're not accidentally matching things out of order.

This becomes more obvious w/ things in codegen where you have easy to spot delimiters, but are also likely to have many duplicate lines in your test program (e.g. most load instructions look the same).

So you use this pattern to match the start of a unique sequence w/ MYCHECK (or whatever your prefix is), and then use MYCHECK-NEXT to make sure the following lines match right afterwards, and not anywhere else.

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