[clang-doc] add enum test

[PeterChou1]

This patch adds a test which test the enum generation for clang-doc.

[llvmbot]

@llvm/pr-subscribers-clang-tools-extra

Author: None (PeterChou1)

Changes

This patch adds a test which test the enum generation for clang-doc.

---

Full diff: https://github.com/llvm/llvm-project/pull/97679.diff

1 Files Affected:

• (added) clang-tools-extra/test/clang-doc/enum.cpp (+38)

diff --git a/clang-tools-extra/test/clang-doc/enum.cpp b/clang-tools-extra/test/clang-doc/enum.cpp
new file mode 100644
index 0000000000000..2f25eaf4e44e2
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/enum.cpp
@@ -0,0 +1,38 @@
+// RUN: clang-doc --format=html --doxygen --output=%t/docs --executor=standalone %s
+// RUN: clang-doc --format=md --doxygen --output=%t/docs --executor=standalone %s
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.html -check-prefix=HTML-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.md -check-prefix=MD-INDEX
+
+/**
+ * @brief For specifying RGB colors
+ */
+enum Color {
+  Red, // Red enums
+  Green, // Green enums
+  Blue // Blue enums
+};
+
+// HTML-INDEX: <h1>Global Namespace</h1>
+// HTML-INDEX: <h2 id="Enums">Enums</h2>
+// HTML-INDEX: <div>
+// HTML-INDEX:   <h3 id="{{([0-9A-F]{40})}}">enum Color</h3>
+// HTML-INDEX:   <ul>
+// HTML-INDEX:     <li>Red</li>
+// HTML-INDEX:     <li>Green</li>
+// HTML-INDEX:     <li>Blue</li>
+// HTML-INDEX:   </ul>
+// HTML-INDEX:   <p>Defined at line 11 of file {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}enum.cpp</p>
+// HTML-INDEX:   <div>
+// HTML-INDEX:     <div></div>
+// HTML-INDEX:   </div>
+// HTML-INDEX: </div>
+
+// MD-INDEX: # Global Namespace
+// MD-INDEX: ## Enums
+// MD-INDEX: | enum Color |
+// MD-INDEX: --
+// MD-INDEX: | Red |
+// MD-INDEX: | Green |
+// MD-INDEX: | Blue |
+// MD-INDEX: *Defined at {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}enum.cpp#11*
+// MD-INDEX: **brief** For specifying RGB colors
\ No newline at end of file

[ilovepi]

should these be doc comments?

[ilovepi]

These seem to be gone now, but isn’t it common to document the enum values? I know we do that in several places in LLVM.

Thinking about other cases, it probably also worth having an “enum class”, an enum within a class, and one in a namespace. I’d suggest also varying in at least one case where the doc comments are: e.g., above the value vs on the same line.

[ilovepi]

This can't work right, can it? you haven't made %t, you also don't need docs, right? It would be good if I didn't have to point these out in every patch... I've given this piece of feedback in almost all of your patches.

[PeterChou1]

sorry I've realize originally that we didn't need to explicitly mkdir but its probably better to specify it

[ilovepi]

Maybe this can be ‘enum class’? We already have a normal enum above.

[PeterChou1]

I did not know that enum classes were a thing, I thought you meant enum embedded in a class, I've update the code

[ilovepi]

yeah, those cases are distinct, so its good to have both.

[ilovepi]

Shouldn’t these be documentation comments? So using /// or the doxygen style comments?

My earlier point was that in LLVM and other projects, there are often documentation comments attached the the enum entries. It would be good to test that. If it doesn’t work, we can add a TODO and a tracking bug on GitHub.

[ilovepi]

LGTM, modulo some nits. I do think you may want to have a separate prefix for the lines, but if you change --check-prefix= to --check-prefixes=HTML-ANIMAL,HTML-ANIMAL-LINE, you should be able to check them w/o having to rewrite everything. Plus keeping the LINE comments right after the source line makes it a lot easier to keep the tests stable.

[ilovepi]

nit: extra newlines

[ilovepi]

This is a lot better, but maybe its better to move this and the HTML line check below the LINE you want to check and then do

enum Color {
// MD-INDEX: *Defined at {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}enum.cpp#[[@LINE-1]]*
// HTML-INDEX: <p>Defined at line [[@LINE-2]] of file {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}enum.cpp</p>

Any remaining checks can go below the class, or these line checks could be MD-INDEX-LINE & HTML-INDEX-LINE, and you can list 2 prefixes to check, then only the 2 line checks would be out of order w/ the rest. WDYT?