[clang-doc] Add another test project to clang-doc #97518
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@llvm/pr-subscribers-clang-tools-extra Author: None (PeterChou1) ChangesThis patches adds more e2e test to clang-doc which tests the html and markdown output.
Patch is 94.38 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/97518.diff 13 Files Affected:
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/database_template.json b/clang-tools-extra/test/clang-doc/Inputs/advance-project/database_template.json
new file mode 100644
index 0000000000000..8e9f814dd055b
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/database_template.json
@@ -0,0 +1,22 @@
+[
+ {
+ "directory": "$test_dir/Inputs/advance-project",
+ "command": "clang++ -o Array.o -I./include ./src/Array.cpp",
+ "file": "./src/Array.cpp"
+ },
+ {
+ "directory": "$test_dir/Inputs/advance-project",
+ "command": "clang++ -o Circle.o -I./include ./src/Circle.cpp",
+ "file": "./src/Circle.cpp"
+ },
+ {
+ "directory": "$test_dir/Inputs/advance-project",
+ "command": "clang++ -o Shape.o -I./include ./src/Shape.cpp",
+ "file": "./src/Shape.cpp"
+ },
+ {
+ "directory": "$test_dir/Inputs/advance-project",
+ "command": "clang++ -o Utils.o -I./include ./src/Utils.cpp",
+ "file": "./src/Utils.cpp"
+ }
+]
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Array.h b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Array.h
new file mode 100644
index 0000000000000..eef5168509159
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Array.h
@@ -0,0 +1,35 @@
+#pragma once
+
+/** @brief Maximum size for the IntArray typedef */
+#define MAX_SIZE 100
+
+/**
+ * @brief Template class for a simple array
+ *
+ * @tparam T The type of elements in the array
+ * @tparam Size The fixed size of the array
+ */
+template <typename T, int Size>
+class Array {
+public:
+ /** @brief Default constructor */
+ Array();
+
+ /**
+ * @brief Array access operator
+ *
+ * @param index The index of the element to access
+ * @return T& Reference to the element at the given index
+ */
+ T& operator[](int index);
+
+ /**
+ * @brief Get the size of the array
+ *
+ * @return int The size of the array
+ */
+ int size() const;
+
+private:
+ T m_data[Size]; /**< The array data */
+};
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Circle.h b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Circle.h
new file mode 100644
index 0000000000000..0188a7832a818
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Circle.h
@@ -0,0 +1,32 @@
+#pragma once
+
+#include "Shape.h"
+#include "Utils.h"
+
+namespace OuterNamespace {
+ namespace InnerNamespace {
+ /**
+ * @brief Circle class, derived from Shape
+ */
+ class Circle : public Shape {
+ public:
+ /**
+ * @brief Constructor
+ *
+ * @param id The unique identifier for the circle
+ * @param radius The radius of the circle
+ */
+ Circle(int id, double radius);
+
+ /**
+ * @brief Implementation of the draw function
+ *
+ * Draws the circle (in this case, prints circle information)
+ */
+ void draw() const override;
+
+ private:
+ double m_radius; /**< The radius of the circle */
+ };
+ }
+}
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Shape.h b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Shape.h
new file mode 100644
index 0000000000000..e2fedeed620cc
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Shape.h
@@ -0,0 +1,49 @@
+#pragma once
+
+/// Outer namespace
+namespace OuterNamespace {
+ /// Inner namespace
+ namespace InnerNamespace {
+ /**
+ * @brief Enum class for colors
+ */
+ enum class Color {
+ Red, /**< Red color */
+ Green, /**< Green color */
+ Blue /**< Blue color */
+ };
+
+ /**
+ * @brief Abstract base class for shapes
+ */
+ class Shape {
+ public:
+ /**
+ * @brief Constructor
+ *
+ * @param id The unique identifier for the shape
+ */
+ explicit Shape(int id);
+
+ /**
+ * @brief Virtual destructor
+ */
+ virtual ~Shape();
+
+ /**
+ * @brief Pure virtual function for drawing the shape
+ */
+ virtual void draw() const = 0;
+
+ /**
+ * @brief Getter for the shape's ID
+ *
+ * @return int The shape's ID
+ */
+ int getId() const;
+
+ private:
+ int m_id; /**< The shape's unique identifier */
+ };
+ }
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Utils.h b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Utils.h
new file mode 100644
index 0000000000000..6e97b6441abe1
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Utils.h
@@ -0,0 +1,38 @@
+#pragma once
+
+/// Anonymous namespace for utility functions
+namespace {
+ /**
+ * @brief Generate a "random" number
+ *
+ * @note This is not actually random in this implementation
+ *
+ * @return int A predetermined "random" number
+ */
+ int getRandomNumber();
+
+ /**
+ * @brief Helper function to convert int to string
+ *
+ * @param value The integer value to convert
+ * @param buffer The char buffer to store the result
+ * @param index Reference to the current index in the buffer
+ */
+ void intToString(int value, char* buffer, int& index);
+
+ /**
+ * @brief Helper function to convert double to string (simplified)
+ *
+ * @param value The double value to convert
+ * @param buffer The char buffer to store the result
+ * @param index Reference to the current index in the buffer
+ */
+ void doubleToString(double value, char* buffer, int& index);
+
+ /**
+ * @brief Helper function to print a string
+ *
+ * @param str The null-terminated string to print
+ */
+ void print(const char* str);
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Array.cpp b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Array.cpp
new file mode 100644
index 0000000000000..a871509cf2b4e
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Array.cpp
@@ -0,0 +1,31 @@
+#include "Array.h"
+
+// Implementation of Array<T, Size>
+
+/**
+* Initializes all elements of the array to their default value.
+*/
+template <typename T, int Size>
+Array<T, Size>::Array() {
+ // Implementation stub
+}
+
+/**
+* Array access operator for Array<T, Size>
+* Provides read and write access to elements in the array.
+* This implementation does not perform bounds checking
+*/
+template <typename T, int Size>
+T& Array<T, Size>::operator[](int index) {
+ // Implementation stub
+ static T dummy;
+ return dummy;
+}
+
+/**
+* Get the size of the array for Array<T, Size>
+*/
+template <typename T, int Size>
+int Array<T, Size>::size() const {
+ return Size;
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Circle.cpp b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Circle.cpp
new file mode 100644
index 0000000000000..c0fe0fe087f7e
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Circle.cpp
@@ -0,0 +1,24 @@
+#include "Circle.h"
+
+namespace OuterNamespace {
+ namespace InnerNamespace {
+
+ /**
+ * Initializes a Circle object with a given ID and radius.
+ */
+ Circle::Circle(int id, double radius) : Shape(id), m_radius(radius) {
+ // Implementation stub
+ }
+
+ /**
+ * This function is responsible for drawing the circle. In a real
+ * implementation, this would perform the actual drawing operation.
+ * In this stub implementation, it simply prints information about
+ * the circle.
+ */
+ void Circle::draw() const {
+ // Implementation stub
+ }
+
+ } // namespace InnerNamespace
+} // namespace OuterNamespace
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Shape.cpp b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Shape.cpp
new file mode 100644
index 0000000000000..95e3f4b8fb40b
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Shape.cpp
@@ -0,0 +1,28 @@
+#include "Shape.h"
+
+namespace OuterNamespace {
+ namespace InnerNamespace {
+
+ /**
+ * Initializes a Shape object with a given ID.
+ */
+ Shape::Shape(int id) : m_id(id) {
+ // Implementation stub
+ }
+
+ /**
+ * Ensures proper cleanup of derived classes.
+ */
+ Shape::~Shape() {
+ // Implementation stub
+ }
+
+ /**
+ * Get unique identifier of the shape
+ */
+ int Shape::getId() const {
+ return m_id;
+ }
+
+ } // namespace InnerNamespace
+} // namespace OuterNamespace
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Utils.cpp b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Utils.cpp
new file mode 100644
index 0000000000000..f5bab5aa39ff4
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Utils.cpp
@@ -0,0 +1,37 @@
+#include "Utils.h"
+
+namespace {
+
+ /**
+ * This function returns a predetermined number to simulate randomness.
+ * In a real implementation, this would use a proper random number generator
+ */
+ int getRandomNumber() {
+ // Implementation stub
+ return 4;
+ }
+
+ /**
+ * Converts an integer value to its string representation and stores
+ * the result in the provided buffer.
+ */
+ void intToString(int value, char* buffer, int& index) {
+ // Implementation stub
+ }
+
+ /**
+ * Converts a double value to its string representation with two decimal
+ * places and stores the result in the provided buffer.
+ */
+ void doubleToString(double value, char* buffer, int& index) {
+ // Implementation stub
+ }
+
+ /**
+ * Prints the provided null-terminated string to the standard output.
+ */
+ void print(const char* str) {
+ // Implementation stub
+ }
+
+} // anonymous namespace
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/advance-project.test b/clang-tools-extra/test/clang-doc/advance-project.test
new file mode 100644
index 0000000000000..762b5b99e7d1a
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/advance-project.test
@@ -0,0 +1,701 @@
+// RUN: sed 's|$test_dir|%/S|g' %S/Inputs/advance-project/database_template.json > %t/build/compile_commands.json
+// RUN: clang-doc --format=html --doxygen --output=%t/docs --executor=all-TUs %t/build/compile_commands.json
+// RUN: clang-doc --format=md --doxygen --output=%t/docs --executor=all-TUs %t/build/compile_commands.json
+// RUN: FileCheck %s -input-file=%t/docs/index_json.js -check-prefix=JSON-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/@nonymous_namespace/index.html -check-prefix=HTML-ANON-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Array.html -check-prefix=HTML-ARRAY
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.html -check-prefix=HTML-GLOBAL-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Circle.html -check-prefix=HTML-CIRCLE
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/index.html -check-prefix=HTML-INNER-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Shape.html -check-prefix=HTML-SHAPE
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/index.html -check-prefix=HTML-OUTER-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/@nonymous_namespace/index.md -check-prefix=MD-ANON-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Array.md -check-prefix=MD-ARRAY
+// RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.md -check-prefix=MD-GLOBAL-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Circle.md -check-prefix=MD-CIRCLE
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/index.md -check-prefix=MD-INNER
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Shape.md -check-prefix=MD-SHAPE
+// RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/index.md -check-prefix=MD-OUTER-INDEX
+// RUN: FileCheck %s -input-file=%t/docs/all_files.md -check-prefix=MD-ALL-FILES
+// RUN: FileCheck %s -input-file=%t/docs/index.md -check-prefix=MD-INDEX
+
+// JSON-INDEX: async function LoadIndex() {
+// JSON-INDEX-NEXT: return{
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "",
+// JSON-INDEX-NEXT: "RefType": "default",
+// JSON-INDEX-NEXT: "Path": "",
+// JSON-INDEX-NEXT: "Children": [
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "@nonymous_namespace",
+// JSON-INDEX-NEXT: "RefType": "namespace",
+// JSON-INDEX-NEXT: "Path": "@nonymous_namespace",
+// JSON-INDEX-NEXT: "Children": []
+// JSON-INDEX-NEXT: },
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "GlobalNamespace",
+// JSON-INDEX-NEXT: "RefType": "namespace",
+// JSON-INDEX-NEXT: "Path": "GlobalNamespace",
+// JSON-INDEX-NEXT: "Children": [
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "Array",
+// JSON-INDEX-NEXT: "RefType": "record",
+// JSON-INDEX-NEXT: "Path": "GlobalNamespace",
+// JSON-INDEX-NEXT: "Children": []
+// JSON-INDEX-NEXT: }
+// JSON-INDEX-NEXT: ]
+// JSON-INDEX-NEXT: },
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "OuterNamespace",
+// JSON-INDEX-NEXT: "RefType": "namespace",
+// JSON-INDEX-NEXT: "Path": "OuterNamespace",
+// JSON-INDEX-NEXT: "Children": [
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "InnerNamespace",
+// JSON-INDEX-NEXT: "RefType": "namespace",
+// JSON-INDEX-NEXT: "Path": "OuterNamespace{{[\/]+}}InnerNamespace",
+// JSON-INDEX-NEXT: "Children": [
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "Circle",
+// JSON-INDEX-NEXT: "RefType": "record",
+// JSON-INDEX-NEXT: "Path": "OuterNamespace{{[\/]+}}InnerNamespace",
+// JSON-INDEX-NEXT: "Children": []
+// JSON-INDEX-NEXT: },
+// JSON-INDEX-NEXT: {
+// JSON-INDEX-NEXT: "USR": "{{([0-9A-F]{40})}}",
+// JSON-INDEX-NEXT: "Name": "Shape",
+// JSON-INDEX-NEXT: "RefType": "record",
+// JSON-INDEX-NEXT: "Path": "OuterNamespace{{[\/]+}}InnerNamespace",
+// JSON-INDEX-NEXT: "Children": []
+// JSON-INDEX-NEXT: }
+// JSON-INDEX-NEXT: ]
+// JSON-INDEX-NEXT: }
+// JSON-INDEX-NEXT: ]
+// JSON-INDEX-NEXT: }
+// JSON-INDEX-NEXT: ]
+// JSON-INDEX-NEXT: };
+// JSON-INDEX-NEXT: }
+
+// HTML-ANON-INDEX: <!DOCTYPE html>
+// HTML-ANON-INDEX-NEXT: <meta charset="utf-8"/>
+// HTML-ANON-INDEX-NEXT: <title>namespace @nonymous_namespace</title>
+// HTML-ANON-INDEX-NEXT: <link rel="stylesheet" href="..{{[\/]}}clang-doc-default-stylesheet.css"/>
+// HTML-ANON-INDEX-NEXT: <script src="..{{[\/]}}index_json.js"></script>
+// HTML-ANON-INDEX-NEXT: <script src="..{{[\/]}}index.js"></script>
+// HTML-ANON-INDEX-NEXT: <header id="project-title"></header>
+// HTML-ANON-INDEX-NEXT: <main>
+// HTML-ANON-INDEX-NEXT: <div id="sidebar-left" path="@nonymous_namespace" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
+// HTML-ANON-INDEX-NEXT: <div id="main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
+// HTML-ANON-INDEX-NEXT: <h1>namespace @nonymous_namespace</h1>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <p> Anonymous namespace for utility functions</p>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: <h2 id="Functions">Functions</h2>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <h3 id="{{([0-9A-F]{40})}}">getRandomNumber</h3>
+// HTML-ANON-INDEX-NEXT: <p>int getRandomNumber()</p>
+// HTML-ANON-INDEX-NEXT: <p>Defined at line 9 of file .{{[\/]}}src{{[\/]}}Utils.cpp</p>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <div></div>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <p> This function returns a predetermined number to simulate randomness. In a real implementation, this would use a proper random number generator</p>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: <h3 id="{{([0-9A-F]{40})}}">intToString</h3>
+// HTML-ANON-INDEX-NEXT: <p>void intToString(int value, char * buffer, int & index)</p>
+// HTML-ANON-INDEX-NEXT: <p>Defined at line 18 of file .{{[\/]}}src{{[\/]}}Utils.cpp</p>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <div></div>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <p> Converts an integer value to its string representation and stores the result in the provided buffer.</p>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: <h3 id="{{([0-9A-F]{40})}}">doubleToString</h3>
+// HTML-ANON-INDEX-NEXT: <p>void doubleToString(double value, char * buffer, int & index)</p>
+// HTML-ANON-INDEX-NEXT: <p>Defined at line 26 of file .{{[\/]}}src{{[\/]}}Utils.cpp</p>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <div></div>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <p> Converts a double value to its string representation with two decimal places and stores the result in the provided buffer.</p>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: <h3 id="{{([0-9A-F]{40})}}">print</h3>
+// HTML-ANON-INDEX-NEXT: <p>void print(const char * str)</p>
+// HTML-ANON-INDEX-NEXT: <p>Defined at line 33 of file .{{[\/]}}src{{[\/]}}Utils.cpp</p>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <div></div>
+// HTML-ANON-INDEX-NEXT: <div>
+// HTML-ANON-INDEX-NEXT: <p> Prints the provided null-terminated string to the standard output.</p>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: </div>
+// HTML-ANON-INDEX-NEXT: <div id="sidebar-right" class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right">
+// HTML-ANON-INDEX-NEXT: <ol>
+// HTML-ANON-INDEX-NEXT: <li>
+// HTML-ANON-INDEX-NEXT: <span>
+// HTML-ANON-INDEX-NEXT: <a href="#Functions">Functions</a>
+// HTML-ANON-INDEX-NEXT: </span>
+// HTML-ANON-INDEX-NEXT: <ul>
+// HTML-ANON-INDEX-NEXT: <li>
+// HTML-ANON-INDEX-NEXT: <span>
+// HTML-ANON-INDEX-NEXT: <a href="#{{([0-9A-F]{40})}}">getRandomNumber</a>
+// HTML-ANON-INDEX-NEXT: </span>
+// HTML-ANON-INDEX-NEXT: </li>
+// HTML-ANON-INDEX-NEXT: <li>
+// HTML-ANON-INDEX-NEXT: <span>
+// HTML-ANON-INDEX-NEXT: <a href="#{{([0-9A-F]{40})}}">intToString</a>
+// HTML-ANON-INDEX-NEXT: </span>
+// HTML-ANON-INDEX-NEXT: </li>
+// HTML-ANON-INDEX-NEXT: <li>
+// HTML-AN...
[truncated]
|
ilovepi
reviewed
Jul 3, 2024
There was a problem hiding this comment.
Thanks for adding more tests. Clang-Doc badly needs more comprehensive test coverage.
I have a few concerns, however, about the testing strategy. Largely, these tests seem to check the exact output, rather than spot checking for particular features. What I mean by that is it seems like these tests are expected to be updated any time we modify clang-doc. There is a certain amount of value in having a few tests that track format changes, but I'm not too sure we want all of our tests to be of that style.
For instance, do we need to check the JS output so precisely? It's good that we'll know the JS output has changed to a certain degree, but I'm not sure that any change is necessarily wrong. So I think it would be good to go through and minimally test for useful output changes, without precisely matching all of the boiler plate HTML.
It's also worth noting that the Markdown is much more concise, and seems to mostly contain the documentation text. We may want to consider testing all the useful output properties w/ Markdown output, but maintain a few tests that verify the HTML formatting and JS bits. That type of strategy is pretty common in LLVM.
Lastly, it seems like this patch is adding a number to different independent tests. It probably makes more sense to add them independently. I'd say at the least, the projects should be split out into independent patches, as well as the 2 standalone tests.
Comment on lines
+4
to
+20
| // RUN: FileCheck %s -input-file=%t/docs/index_json.js -check-prefix=JSON-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/@nonymous_namespace/index.html -check-prefix=HTML-ANON-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Array.html -check-prefix=HTML-ARRAY | ||
| // RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.html -check-prefix=HTML-GLOBAL-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Circle.html -check-prefix=HTML-CIRCLE | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/index.html -check-prefix=HTML-INNER-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Shape.html -check-prefix=HTML-SHAPE | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/index.html -check-prefix=HTML-OUTER-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/@nonymous_namespace/index.md -check-prefix=MD-ANON-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/Array.md -check-prefix=MD-ARRAY | ||
| // RUN: FileCheck %s -input-file=%t/docs/GlobalNamespace/index.md -check-prefix=MD-GLOBAL-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Circle.md -check-prefix=MD-CIRCLE | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/index.md -check-prefix=MD-INNER | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/InnerNamespace/Shape.md -check-prefix=MD-SHAPE | ||
| // RUN: FileCheck %s -input-file=%t/docs/OuterNamespace/index.md -check-prefix=MD-OUTER-INDEX | ||
| // RUN: FileCheck %s -input-file=%t/docs/all_files.md -check-prefix=MD-ALL-FILES | ||
| // RUN: FileCheck %s -input-file=%t/docs/index.md -check-prefix=MD-INDEX |
There was a problem hiding this comment.
It's generally fine, but -input-file= isn't used much w/ FileCheck. Typically the output is piped in, but just giving it a second file argument is also fine. Something like FileCheck %s < path/to/other/file -check-prefix=Foo may be a bit more typical, and a bit shorter. -input-file= isn't wrong, but you're adding more tests w/ this pattern.
ilovepi
reviewed
Jul 3, 2024
clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Array.cpp
Outdated
Show resolved
Hide resolved
PeterChou1
changed the title
|
I've split this pr into 4 including this PR
|
ilovepi
requested changes
Jul 10, 2024
There was a problem hiding this comment.
I'm a bit confused by the "advanced project", as it largely seems to be minor extensions to the basic project. I would expect that an "advanced project" would use a complicated structure and be much larger. IMO if you're only adding some more language features, then they should be added to the existing basic_project already in tree.
|
|
Closing wasn’t necessary. The changes here could have just been made the the basic project instead of as new files. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This patch adds another project to clang-doc test. This project tests the code path of clang-doc for markdown and html generation. It tests for: