[clang-doc] Add basic e2e test #93928

PeterChou1 · 2024-05-31T06:23:18Z

Adds e2e tests for clang-doc, which serves as useful test against regression in the html output. It also serves as a helpful tool for code review as we can see the diffs to clang-docs output

Closes #93925

llvmbot · 2024-05-31T06:23:52Z

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

Author: None (PeterChou1)

Changes

issue: #93925

Patch is 26.87 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/93928.diff

10 Files Affected:

(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.cpp (+21)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.h (+46)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.cpp (+11)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.h (+35)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.cpp (+12)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.h (+37)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Shape.h (+30)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json (+22)
(added) clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/main.cpp (+25)
(added) clang-tools-extra/test/clang-doc/clang-doc-project1.cpp (+370)

diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.cpp b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.cpp
new file mode 100644
index 0000000000000..df1778c3b9d55
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.cpp
@@ -0,0 +1,21 @@
+#include "Calculator.h"
+#include <stdexcept>
+
+int Calculator::add(int a, int b) {
+    return a + b;
+}
+
+int Calculator::subtract(int a, int b) {
+    return a - b;
+}
+
+int Calculator::multiply(int a, int b) {
+    return a * b;
+}
+
+double Calculator::divide(int a, int b) {
+    if (b == 0) {
+        throw std::invalid_argument("Division by zero");
+    }
+    return static_cast<double>(a) / b;
+}
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.h b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.h
new file mode 100644
index 0000000000000..6811834bc0159
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Calculator.h
@@ -0,0 +1,46 @@
+#pragma once
+
+/**
+ * @brief A simple calculator class.
+ *
+ * Provides basic arithmetic operations.
+ */
+class Calculator {
+public:
+    /**
+     * @brief Adds two integers.
+     *
+     * @param a First integer.
+     * @param b Second integer.
+     * @return int The sum of a and b.
+     */
+    int add(int a, int b);
+
+    /**
+     * @brief Subtracts the second integer from the first.
+     *
+     * @param a First integer.
+     * @param b Second integer.
+     * @return int The result of a - b.
+     */
+    int subtract(int a, int b);
+
+    /**
+     * @brief Multiplies two integers.
+     *
+     * @param a First integer.
+     * @param b Second integer.
+     * @return int The product of a and b.
+     */
+    int multiply(int a, int b);
+
+    /**
+     * @brief Divides the first integer by the second.
+     *
+     * @param a First integer.
+     * @param b Second integer.
+     * @return double The result of a / b.
+     * @throw std::invalid_argument if b is zero.
+     */
+    double divide(int a, int b);
+};
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.cpp b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.cpp
new file mode 100644
index 0000000000000..823384a4d97e8
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.cpp
@@ -0,0 +1,11 @@
+#include "Circle.h"
+
+Circle::Circle(double radius) : radius_(radius) {}
+
+double Circle::area() const {
+    return 3.141 * radius_ * radius_;
+}
+
+double Circle::perimeter() const {
+    return 3.141 * radius_;
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.h b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.h
new file mode 100644
index 0000000000000..7bee3ffa92539
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Circle.h
@@ -0,0 +1,35 @@
+#pragma once
+
+#include "Shape.h"
+
+/**
+ * @brief Circle class derived from Shape.
+ *
+ * Represents a circle with a given radius.
+ */
+class Circle : public Shape {
+public:
+    /**
+     * @brief Constructs a new Circle object.
+     *
+     * @param radius Radius of the circle.
+     */
+    Circle(double radius);
+
+    /**
+     * @brief Calculates the area of the circle.
+     *
+     * @return double The area of the circle.
+     */
+    double area() const override;
+
+    /**
+     * @brief Calculates the perimeter of the circle.
+     *
+     * @return double The perimeter of the circle.
+     */
+    double perimeter() const override;
+
+private:
+    double radius_; ///< Radius of the circle.
+};
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.cpp b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.cpp
new file mode 100644
index 0000000000000..7ffc769157ebc
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.cpp
@@ -0,0 +1,12 @@
+#include "Rectangle.h"
+
+Rectangle::Rectangle(double width, double height)
+        : width_(width), height_(height) {}
+
+double Rectangle::area() const {
+    return width_ * height_;
+}
+
+double Rectangle::perimeter() const {
+    return 2 * (width_ + height_);
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.h b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.h
new file mode 100644
index 0000000000000..8c6223a4f6180
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Rectangle.h
@@ -0,0 +1,37 @@
+#pragma once
+
+#include "Shape.h"
+
+/**
+ * @brief Rectangle class derived from Shape.
+ *
+ * Represents a rectangle with a given width and height.
+ */
+class Rectangle : public Shape {
+public:
+    /**
+     * @brief Constructs a new Rectangle object.
+     *
+     * @param width Width of the rectangle.
+     * @param height Height of the rectangle.
+     */
+    Rectangle(double width, double height);
+
+    /**
+     * @brief Calculates the area of the rectangle.
+     *
+     * @return double The area of the rectangle.
+     */
+    double area() const override;
+
+    /**
+     * @brief Calculates the perimeter of the rectangle.
+     *
+     * @return double The perimeter of the rectangle.
+     */
+    double perimeter() const override;
+
+private:
+    double width_; ///< Width of the rectangle.
+    double height_; ///< Height of the rectangle.
+};
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Shape.h b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Shape.h
new file mode 100644
index 0000000000000..e5c5d4c9e4412
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/Shape.h
@@ -0,0 +1,30 @@
+#pragma once
+
+/**
+ * @brief Abstract base class for shapes.
+ *
+ * Provides a common interface for different types of shapes.
+ */
+class Shape {
+public:
+    /**
+     * @brief Virtual destructor.
+     */
+    virtual ~Shape() {}
+
+    /**
+     * @brief Calculates the area of the shape.
+     *
+     * @return double The area of the shape.
+     */
+    virtual double area() const = 0;
+
+    /**
+     * @brief Calculates the perimeter of the shape.
+     *
+     * @return double The perimeter of the shape.
+     */
+    virtual double perimeter() const = 0;
+};
+
+
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json
new file mode 100644
index 0000000000000..0549c5b718f08
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json
@@ -0,0 +1,22 @@
+[
+{
+  "directory": "$test_dir/build",
+  "command": "clang++ -o main.o -I../include $test_dir/src/main.cpp",
+  "file": "$test_dir/src/main.cpp"
+},
+{
+  "directory": "$test_dir/build",
+  "command": "clang++ -o Calculator.o -I../include $test_dir/src/Calculator.cpp",
+  "file": "$test_dir/src/Calculator.cpp"
+},
+{
+  "directory": "$test_dir/build",
+  "command": "clang++ -o Circle.o -I../include $test_dir/src/Circle.cpp",
+  "file": "$test_dir/src/Circle.cpp"
+},
+{
+  "directory": "$test_dir/build",
+  "command": "clang++ -o Rectangle.o -I../include $test_dir/src/Rectangle.cpp",
+  "file": "$test_dir/src/Rectangle.cpp"
+}
+]
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/main.cpp b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/main.cpp
new file mode 100644
index 0000000000000..e20732c7de371
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/main.cpp
@@ -0,0 +1,25 @@
+#include <iostream>
+#include "Calculator.h"
+#include "Circle.h"
+#include "Rectangle.h"
+
+int main() {
+    // Calculator
+    Calculator calc;
+    std::cout << "Add: " << calc.add(3, 4) << std::endl;
+    std::cout << "Subtract: " << calc.subtract(10, 5) << std::endl;
+    std::cout << "Multiply: " << calc.multiply(2, 3) << std::endl;
+    std::cout << "Divide: " << calc.divide(10, 2) << std::endl;
+
+    // Circle
+    Circle circle(5.0);
+    std::cout << "Circle Area: " << circle.area() << std::endl;
+    std::cout << "Circle Perimeter: " << circle.perimeter() << std::endl;
+
+    // Rectangle
+    Rectangle rectangle(4.0, 6.0);
+    std::cout << "Rectangle Area: " << rectangle.area() << std::endl;
+    std::cout << "Rectangle Perimeter: " << rectangle.perimeter() << std::endl;
+
+    return 0;
+}
\ No newline at end of file
diff --git a/clang-tools-extra/test/clang-doc/clang-doc-project1.cpp b/clang-tools-extra/test/clang-doc/clang-doc-project1.cpp
new file mode 100644
index 0000000000000..c382396ea4cab
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/clang-doc-project1.cpp
@@ -0,0 +1,370 @@
+// RUN: mkdir -p %T/clang-doc/build
+// RUN: mkdir -p %T/clang-doc/include
+// RUN: mkdir -p %T/clang-doc/src
+// RUN: mkdir -p %T/clang-doc/docs
+// RUN: sed 's|$test_dir|%/T/clang-doc|g' %S/Inputs/clang-doc-project1/database_template.json > %T/clang-doc/build/compile_commands.json
+// RUN: cp %S/Inputs/clang-doc-project1/*.h  %T/clang-doc/include
+// RUN: cp %S/Inputs/clang-doc-project1/*.cpp %T/clang-doc/src
+// RUN: cd %T/clang-doc/build
+// RUN: clang-doc --format=html --repository=github.com --executor=all-TUs --output=%T/clang-doc/docs ./compile_commands.json
+// RUN: FileCheck -input-file=%T/clang-doc/docs/index_json.js -check-prefix=CHECK-JSON-INDEX %s
+// RUN: FileCheck -input-file=%T/clang-doc/docs/GlobalNamespace/Shape.html -check-prefix=CHECK-HTML-SHAPE %s
+// RUN: FileCheck -input-file=%T/clang-doc/docs/GlobalNamespace/Calculator.html -check-prefix=CHECK-HTML-CALC %s
+// RUN: FileCheck -input-file=%T/clang-doc/docs/GlobalNamespace/Rectangle.html -check-prefix=CHECK-HTML-RECTANGLE %s
+// RUN: FileCheck -input-file=%T/clang-doc/docs/GlobalNamespace/Circle.html -check-prefix=CHECK-HTML-CIRCLE %s
+
+// CHECK-JSON-INDEX: var JsonIndex = `
+// CHECK-JSON-INDEX: {
+// CHECK-JSON-INDEX:   "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:   "Name": "",
+// CHECK-JSON-INDEX:   "RefType": "default",
+// CHECK-JSON-INDEX:   "Path": "",
+// CHECK-JSON-INDEX:   "Children": [
+// CHECK-JSON-INDEX:     {
+// CHECK-JSON-INDEX:       "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:       "Name": "GlobalNamespace",
+// CHECK-JSON-INDEX:       "RefType": "namespace",
+// CHECK-JSON-INDEX:       "Path": "GlobalNamespace",
+// CHECK-JSON-INDEX:       "Children": [
+// CHECK-JSON-INDEX:         {
+// CHECK-JSON-INDEX:           "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:           "Name": "Calculator",
+// CHECK-JSON-INDEX:           "RefType": "record",
+// CHECK-JSON-INDEX:           "Path": "GlobalNamespace",
+// CHECK-JSON-INDEX:           "Children": []
+// CHECK-JSON-INDEX:         },
+// CHECK-JSON-INDEX:         {
+// CHECK-JSON-INDEX:           "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:           "Name": "Circle",
+// CHECK-JSON-INDEX:           "RefType": "record",
+// CHECK-JSON-INDEX:           "Path": "GlobalNamespace",
+// CHECK-JSON-INDEX:           "Children": []
+// CHECK-JSON-INDEX:         },
+// CHECK-JSON-INDEX:         {
+// CHECK-JSON-INDEX:           "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:           "Name": "Rectangle",
+// CHECK-JSON-INDEX:           "RefType": "record",
+// CHECK-JSON-INDEX:           "Path": "GlobalNamespace",
+// CHECK-JSON-INDEX:           "Children": []
+// CHECK-JSON-INDEX:         },
+// CHECK-JSON-INDEX:         {
+// CHECK-JSON-INDEX:           "USR": "{{([0-9A-F]{40})}}",
+// CHECK-JSON-INDEX:           "Name": "Shape",
+// CHECK-JSON-INDEX:           "RefType": "record",
+// CHECK-JSON-INDEX:           "Path": "GlobalNamespace",
+// CHECK-JSON-INDEX:           "Children": []
+// CHECK-JSON-INDEX:         }
+// CHECK-JSON-INDEX:       ]
+// CHECK-JSON-INDEX:     }
+// CHECK-JSON-INDEX:   ]
+// CHECK-JSON-INDEX: }`;
+
+// CHECK-HTML-SHAPE: <!DOCTYPE html>
+// CHECK-HTML-SHAPE: <meta charset="utf-8"/>
+// CHECK-HTML-SHAPE: <title>class Shape</title>
+// CHECK-HTML-SHAPE: <link rel="stylesheet" href="{{.*}}clang-doc-default-stylesheet.css"/>
+// CHECK-HTML-SHAPE: <script src="{{.*}}index.js"></script>
+// CHECK-HTML-SHAPE: <script src="{{.*}}index_json.js"></script>
+// CHECK-HTML-SHAPE: <header id="project-title"></header>
+// CHECK-HTML-SHAPE: <main>
+// CHECK-HTML-SHAPE:   <div id="sidebar-left" path="GlobalNamespace" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
+// CHECK-HTML-SHAPE:   <div id="main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
+// CHECK-HTML-SHAPE:     <h1>class Shape</h1>
+// CHECK-HTML-SHAPE:     <p>Defined at line 8 of file {{.*}}Shape.h</p>
+// CHECK-HTML-SHAPE:     <div>
+// CHECK-HTML-SHAPE:       <div>
+// CHECK-HTML-SHAPE:         <p> Provides a common interface for different types of shapes.</p>
+// CHECK-HTML-SHAPE:       </div>
+// CHECK-HTML-SHAPE:     </div>
+// CHECK-HTML-SHAPE:     <h2 id="Functions">Functions</h2>
+// CHECK-HTML-SHAPE:     <div>
+// CHECK-HTML-SHAPE:       <h3 id="{{([0-9A-F]{40})}}">~Shape</h3>
+// CHECK-HTML-SHAPE:       <p>public void ~Shape()</p>
+// CHECK-HTML-SHAPE:       <p>Defined at line 13 of file {{.*}}Shape.h</p>
+// CHECK-HTML-SHAPE:       <div>
+// CHECK-HTML-SHAPE:         <div></div>
+// CHECK-HTML-SHAPE:       </div>
+// CHECK-HTML-SHAPE:       <h3 id="{{([0-9A-F]{40})}}">area</h3>
+// CHECK-HTML-SHAPE:       <p>public double area()</p>
+// CHECK-HTML-SHAPE:       <div>
+// CHECK-HTML-SHAPE:         <div></div>
+// CHECK-HTML-SHAPE:       </div>
+// CHECK-HTML-SHAPE:       <h3 id="{{([0-9A-F]{40})}}">perimeter</h3>
+// CHECK-HTML-SHAPE:       <p>public double perimeter()</p>
+// CHECK-HTML-SHAPE:       <div>
+// CHECK-HTML-SHAPE:         <div></div>
+// CHECK-HTML-SHAPE:       </div>
+// CHECK-HTML-SHAPE:     </div>
+// CHECK-HTML-SHAPE:   </div>
+// CHECK-HTML-SHAPE:   <div id="sidebar-right" class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right">
+// CHECK-HTML-SHAPE:     <ol>
+// CHECK-HTML-SHAPE:       <li>
+// CHECK-HTML-SHAPE:         <span>
+// CHECK-HTML-SHAPE:           <a href="#Functions">Functions</a>
+// CHECK-HTML-SHAPE:         </span>
+// CHECK-HTML-SHAPE:         <ul>
+// CHECK-HTML-SHAPE:           <li>
+// CHECK-HTML-SHAPE:             <span>
+// CHECK-HTML-SHAPE:               <a href="#{{([0-9A-F]{40})}}">~Shape</a>
+// CHECK-HTML-SHAPE:             </span>
+// CHECK-HTML-SHAPE:           </li>
+// CHECK-HTML-SHAPE:           <li>
+// CHECK-HTML-SHAPE:             <span>
+// CHECK-HTML-SHAPE:               <a href="#{{([0-9A-F]{40})}}">area</a>
+// CHECK-HTML-SHAPE:             </span>
+// CHECK-HTML-SHAPE:           </li>
+// CHECK-HTML-SHAPE:           <li>
+// CHECK-HTML-SHAPE:             <span>
+// CHECK-HTML-SHAPE:               <a href="#{{([0-9A-F]{40})}}">perimeter</a>
+// CHECK-HTML-SHAPE:             </span>
+// CHECK-HTML-SHAPE:           </li>
+// CHECK-HTML-SHAPE:         </ul>
+// CHECK-HTML-SHAPE:       </li>
+// CHECK-HTML-SHAPE:     </ol>
+// CHECK-HTML-SHAPE:   </div>
+// CHECK-HTML-SHAPE: </main>
+
+// CHECK-HTML-CALC: <!DOCTYPE html>
+// CHECK-HTML-CALC: <meta charset="utf-8"/>
+// CHECK-HTML-CALC: <title>class Calculator</title>
+// CHECK-HTML-CALC: <link rel="stylesheet" href="{{.*}}clang-doc-default-stylesheet.css"/>
+// CHECK-HTML-CALC: <script src="{{.*}}index.js"></script>
+// CHECK-HTML-CALC: <script src="{{.*}}index_json.js"></script>
+// CHECK-HTML-CALC: <header id="project-title"></header>
+// CHECK-HTML-CALC: <main>
+// CHECK-HTML-CALC:   <div id="sidebar-left" path="GlobalNamespace" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
+// CHECK-HTML-CALC:   <div id="main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
+// CHECK-HTML-CALC:     <h1>class Calculator</h1>
+// CHECK-HTML-CALC:     <p>Defined at line 8 of file {{.*}}Calculator.h</p>
+// CHECK-HTML-CALC:     <div>
+// CHECK-HTML-CALC:       <div>
+// CHECK-HTML-CALC:         <p> Provides basic arithmetic operations.</p>
+// CHECK-HTML-CALC:       </div>
+// CHECK-HTML-CALC:     </div>
+// CHECK-HTML-CALC:     <h2 id="Functions">Functions</h2>
+// CHECK-HTML-CALC:     <div>
+// CHECK-HTML-CALC:       <h3 id="{{([0-9A-F]{40})}}">add</h3>
+// CHECK-HTML-CALC:       <p>public int add(int a, int b)</p>
+// CHECK-HTML-CALC:       <p>Defined at line 4 of file {{.*}}Calculator.cpp</p>
+// CHECK-HTML-CALC:       <div>
+// CHECK-HTML-CALC:         <div></div>
+// CHECK-HTML-CALC:       </div>
+// CHECK-HTML-CALC:       <h3 id="{{([0-9A-F]{40})}}">subtract</h3>
+// CHECK-HTML-CALC:       <p>public int subtract(int a, int b)</p>
+// CHECK-HTML-CALC:       <p>Defined at line 8 of file {{.*}}Calculator.cpp</p>
+// CHECK-HTML-CALC:       <div>
+// CHECK-HTML-CALC:         <div></div>
+// CHECK-HTML-CALC:       </div>
+// CHECK-HTML-CALC:       <h3 id="{{([0-9A-F]{40})}}">multiply</h3>
+// CHECK-HTML-CALC:       <p>public int multiply(int a, int b)</p>
+// CHECK-HTML-CALC:       <p>Defined at line 12 of file {{.*}}Calculator.cpp</p>
+// CHECK-HTML-CALC:       <div>
+// CHECK-HTML-CALC:         <div></div>
+// CHECK-HTML-CALC:       </div>
+// CHECK-HTML-CALC:       <h3 id="{{([0-9A-F]{40})}}">divide</h3>
+// CHECK-HTML-CALC:       <p>public double divide(int a, int b)</p>
+// CHECK-HTML-CALC:       <p>Defined at line 16 of file {{.*}}Calculator.cpp</p>
+// CHECK-HTML-CALC:       <div>
+// CHECK-HTML-CALC:         <div></div>
+// CHECK-HTML-CALC:       </div>
+// CHECK-HTML-CALC:     </div>
+// CHECK-HTML-CALC:   </div>
+// CHECK-HTML-CALC:   <div id="sidebar-right" class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right">
+// CHECK-HTML-CALC:     <ol>
+// CHECK-HTML-CALC:       <li>
+// CHECK-HTML-CALC:         <span>
+// CHECK-HTML-CALC:           <a href="#Functions">Functions</a>
+// CHECK-HTML-CALC:         </span>
+// CHECK-HTML-CALC:         <ul>
+// CHECK-HTML-CALC:           <li>
+// CHECK-HTML-CALC:             <span>
+// CHECK-HTML-CALC:               <a href="#{{([0-9A-F]{40})}}">add</a>
+// CHECK-HTML-CALC:             </span>
+// CHECK-HTML-CALC:           </li>
+// CHECK-HTML-CALC:           <li>
+// CHECK-HTML-CALC:             <span>
+// CHECK-HTML-CALC:               <a href="#{{([0-9A-F]{40})}}">subtract</a>
+// CHECK-HTML-CALC:             </span>
+// CHECK-HTML-CALC:           </li>
+// CHECK-HTML-CALC:           <li>
+// CHECK-HTML-CALC:             <span>
+// CHECK-HTML-CALC:               <a href="#{{([0-9A-F]{40})}}">multiply</a>
+// CHECK-HTML-CALC:             </span>
+// CHECK-HTML-CALC:           </li>
+// CHECK-HTML-CALC:           <li>
+// CHECK-HTML-CALC:             <span>
+// CHECK-HTML-CALC:               <a href="#{{([0-9A-F]{40})}}">divide</a>
+// CHECK-HTML-CALC:             </span>
+// CHECK-HTML-CALC:           </li>
+// CHECK-HTML-CALC:         </ul>
+// CHECK-HTML-CALC:       </li>
+// CHECK-HTML-CALC:     </ol>
+// CHECK-HTML-CALC:   </div>
+// CHECK-HTML-CALC: </main>
+
+// CHECK-HTML-RECTANGLE: <!DOCTYPE html>
+// CHECK-HTML-RECTANGLE: <meta charset="utf-8"/>
+// CHECK-HTML-RECTANGLE: <title>class Rectangle</title>
+// CHECK-HTML-RECTANGLE: <link rel="stylesheet" href="{{.*}}clang-doc-default-stylesheet.css"/>
+// CHECK-HTML-RECTANGLE: <script src="{{.*}}index.js"></script>
+// CHECK-HTML-RECTANGLE: <script src="{{.*}}index_json.js"></script>
+// CHECK-HTML-RECTANGLE: <header id="project-title"></header>
+// CHECK-HTML-RECTANGLE: <main>
+// CHECK-HTML-RECTANGLE:   <div id="sidebar-left" path="GlobalNamespace" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
+// CHECK-HTML-RECTANGLE:   <div id="main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
+// CHECK-HTML-RECTANGLE:     <h1>class Rectangle</h1>
+// CHECK-HTML-RECTANGLE:     <p>Defined at line 10 of file {{.*}}Rectangle.h</p>
+// CHECK-HTML-RECTANGLE:     <div>
+// CHECK-HTML-RECTANGLE:       <div>
+// CHECK-HTML-RECTANGLE:         <p> Represents a rectangle with a given width and height.</p>
+// CHECK-HTML-RECTANGLE:       </div>
+// CHECK-HTML-RECTANGLE:     </div>
+// CHECK-HTML-RECTANGLE:     <p>
+// CHECK-HTML-RECTANGLE:       Inherits from
+// CHECK-HTML-RECTANGLE:       <a href="Shape.html">Shape</a>
+// CHECK-HTML-RECTANGLE:     </p>
+// CHECK-...
[truncated]

ilovepi · 2024-05-31T17:58:55Z

Can you update the title and description to match the normal format as discussed previously? I see you've followed that in your subsequent commits, but it isn't reflected there, probably because they're commits after the initial one.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json

clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/main.cpp

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

github-actions · 2024-06-06T19:41:18Z

✅ With the latest revision this PR passed the Python code formatter.

ilovepi · 2024-06-06T20:53:19Z

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

+// RUN: cp %S/Inputs/clang-doc-project1/*.h  %t/clang-doc/include
+// RUN: cp %S/Inputs/clang-doc-project1/*.cpp %t/clang-doc/src


Why do you need to copy the sources? can't you have the whole "project" under Inputs and just use that path? For example, why aren't the headers already in a directory called include and the cpp files under src?

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

ilovepi

Screen shots don't belong in the commit message. Public URLs are often OK for reference to LLVM source or a standards doc, but do make sure those are permalinks, and not pointed to something on say the main branch, which will change over time.

In general, prefer including text and format it using markdown. This will show up in terminals and the GitHub UI equally well.

ilovepi · 2024-06-06T21:09:22Z

Also, I just noticed that the first comment has an @ in it. The first comment in Github is special, as its really the body of the commit message, and will become that when you hit Squash and merge. Your question for @petrhosek may not even have been sent, as I don't know how github handles that. Please update the first message to be appropriate for the commit body, and copy any questions/context you have to another comment.

clang-tools-extra/test/lit.cfg.py

ilovepi · 2024-06-06T21:48:48Z

A few meta comments on the particulars of the commit title and message:

Please change the title to only have the [clang-doc] tag. This doesn't impact clang at all. We use the[tag] Title convention to make it easy to understand where the changes are, and what they affect. Here something appropriate is either [clang-doc] Add basic e2e test or [clang-doc][test] Add basic e2e test.
The first comment on GitHub is special in a PR, as its the commit body. Ideally, it would have a description of what your change is doing and why. For tests, its often beneficial to put some rationale or explanation in the commit message, if there isn't a place to document it in the source.
If you only reference an issue, it just creates a cross ref. If your commit should fix or close the issue, there are special keywords you can put in the commit body for that (see this reference).

ilovepi

All of the changes related to allowing a different path for the assets belong in their own PR, or if they're invasive, perhaps multiple PRs.

github-actions · 2024-06-07T00:38:30Z

✅ With the latest revision this PR passed the C/C++ code formatter.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

ilovepi · 2024-06-07T01:13:08Z

Also, the current PR only has tests for the HTML output. Please file separate bugs for the other formats, and be sure to follow up with more tests for those formats.

PeterChou1 · 2024-06-07T05:51:22Z

I split the PR into 2 this PR relies on #94717 which adds the --asset option

ilovepi

This is getting pretty close, but there's a few things I'd like to iron out before landing. Plus I believe this has a dependency on the --assets flag changes.

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

ilovepi · 2024-06-07T17:50:28Z

clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json

+[
+  {
+    "directory": "$test_dir/build",
+    "command": "clang++ -o Calculator.o -I../include $test_dir/src/Calculator.cpp",


Suggested change

"command": "clang++ -o Calculator.o -I../include $test_dir/src/Calculator.cpp",

"command": "clang++ -o Calculator.o -I../include ../src/Calculator.cpp",

This can be relative too. Same in other lines.

ilovepi · 2024-06-07T17:52:32Z

clang-tools-extra/test/clang-doc/Inputs/clang-doc-project1/database_template.json

@@ -0,0 +1,17 @@
+[
+  {
+    "directory": "$test_dir/build",


Would the following work? It would be really nice if we could make this operate w/o the sed command.

Suggested change

"directory": "$test_dir/build",

"directory": "./build",

or

Suggested change

"directory": "$test_dir/build",

"directory": ".",

I tried getting relative paths to work but it didn't seem to work

clang-tools-extra/test/clang-doc/clang-doc-project1.cpp

petrhosek · 2024-06-12T01:17:39Z

Do we really need a full CSS when we're only checking the HTML? Could we just include a super minimal (or even empty) CSS?

PeterChou1 · 2024-06-12T06:30:40Z

Do we really need a full CSS when we're only checking the HTML? Could we just include a super minimal (or even empty) CSS?

I just realize we probably don't need any css or js we just need the files

PeterChou1 · 2024-06-13T05:18:36Z

I think this finally works i think we could also shelve #94717
since I wrote that pr to get around the fact that we can't copy assets

ilovepi · 2024-06-13T17:12:16Z

clang-tools-extra/clang-doc/tool/CMakeLists.txt

+
+add_custom_target(copy-clang-doc-assets
+        COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/../assets" "${CMAKE_BINARY_DIR}/share/clang"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/../assets"
+        COMMENT "Copying Clang-Doc Assets"
+)
+set_target_properties(copy-clang-doc-assets PROPERTIES FOLDER "Clang-Doc/Assets")
+add_dependencies(clang-doc copy-clang-doc-assets)


Let's leave this to #95187. The copying of assets is a separate issue, and that is already under review.

ilovepi

The files in the Input folder don't need a clang-doc prefix. They're already under test/clang-doc

I'd also suggest renaming the folder from project1 to something like basic-project.

ilovepi

Also, I'm not sure I understand the need for empty files. If we don't need them, then lets remove them. If you need to use an empty file for some test, you can create those w/ touch in the test itself, but I don't see those referenced at all in basic-project.test.

ilovepi · 2024-06-13T17:30:59Z

I think this finally works i think we could also shelve #94717 since I wrote that pr to get around the fact that we can't copy assets

I think being able to override the css and js files is still probably useful.

What I'm wondering, now is that if the .css and .js files can be empty, is there a reason its a fatal error to not have those available? Again, that's an independent change, but if it doesn't then we may not need to update the cmake in #95187 at all.

If that is the case, we should stop making it a fatal error if clang-doc can't find the asset files. Then, I can abandon #95187, and you can probably land #94717, since it won't fail anymore. Tests can then use the --asset= flag as needed to customize the HTML. @petrhosek WDYT?

ilovepi · 2024-06-13T19:40:23Z

Petr and I spoke offline. #95187, is still independently useful, since it matches our normal conventions about the build directory matching the install directory.

I think we agree on it not being a fatal error, though if it can generate HTML without those assets. #94717, is also useful.

…ources

clang-tools-extra/test/clang-doc/basic-project.test

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

nico · 2024-06-22T20:46:47Z

clang-tools-extra/test/clang-doc/basic-project.test

+// HTML-SHAPE-NEXT: <meta charset="utf-8"/>
+// HTML-SHAPE-NEXT: <title>class Shape</title>
+// HTML-SHAPE-NEXT: <link rel="stylesheet" href="../clang-doc-default-stylesheet.css"/>
+// HTML-SHAPE-NEXT: <script src="../index.js"></script>


This uses ../index.js while the other three use {{.*}}/index.js. Shouldn't all four be consistent?

nico · 2024-06-22T20:54:52Z

clang-tools-extra/test/clang-doc/Inputs/basic-project/src/Calculator.cpp

@@ -0,0 +1,21 @@
+#include "Calculator.h"
+#include <stdexcept>


Tests must be freestanding and cannot include system headers.

Removes stdexecpt from clang-doc test introduced in #93928 since it violates the rule that test must be freestanding

bogner · 2024-07-03T19:04:45Z

This test fails on multi-config cmake generators (cmake -G 'Visual Studio etc), exposing an existing bug in clang-doc. Since binaries end up under a subdirectory like build/Release/bin but the default json and such end up in build/share/clang-doc, running clang-doc from the bin dir doesn't find the default configs.

There's one attempt to fix this here: #97505

Adds e2e tests for clang-doc, which serves as useful test against regression in the html output. It also serves as a helpful tool for code review as we can see the diffs to clang-docs output Closes llvm#93925

Removes stdexecpt from clang-doc test introduced in llvm#93928 since it violates the rule that test must be freestanding

llvmbot added the clang-tools-extra label May 31, 2024

ilovepi requested changes May 31, 2024

View reviewed changes

PeterChou1 changed the title ~~Clang doc test~~ [clang][clang-doc] Add basic e2e test to clang-doc May 31, 2024

ilovepi reviewed Jun 6, 2024

View reviewed changes

ilovepi requested changes Jun 6, 2024

View reviewed changes

ilovepi reviewed Jun 6, 2024

View reviewed changes

clang-tools-extra/test/lit.cfg.py Outdated Show resolved Hide resolved

PeterChou1 changed the title ~~[clang][clang-doc] Add basic e2e test to clang-doc~~ [clang-doc] Add basic e2e test Jun 6, 2024

ilovepi reviewed Jun 7, 2024

View reviewed changes

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp Outdated Show resolved Hide resolved

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp Outdated Show resolved Hide resolved

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp Outdated Show resolved Hide resolved

PeterChou1 mentioned this pull request Jun 7, 2024

[clang-doc] Add --asset option to clang-doc #94717

Merged

[clang-doc] add basic e2e test

219df18

PeterChou1 force-pushed the clang-doc-test branch from 3f343f3 to 219df18 Compare June 7, 2024 05:49

ilovepi reviewed Jun 7, 2024

View reviewed changes

[clang][clang-doc] simplify e2e test commands

ccd44f6

PeterChou1 added 3 commits June 12, 2024 12:40

[clang][clang-doc] remove contents in files

d00c4bc

[clang][clang-doc] make cmake auto copy asset on build

923383c

[clang][clang-doc] use copy_directory instead if different

86638fb

ilovepi reviewed Jun 13, 2024

View reviewed changes

PeterChou1 added 4 commits June 14, 2024 16:36

[clang][clang-doc] remove fatal condition for failing to generate res…

6aed7d0

…ources

[clang][clang-doc] fix conflicts

922e648

rename clang-doc-project1 to basic-project

b5680a5

[clang][clang-doc] rename sed command for basic-project

ec188db

ilovepi reviewed Jun 14, 2024

View reviewed changes

clang-tools-extra/test/clang-doc/basic-project.test Outdated Show resolved Hide resolved

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp Outdated Show resolved Hide resolved

[clang][clang-doc] modify warnings

7ca9137

ilovepi approved these changes Jun 18, 2024

View reviewed changes

ilovepi merged commit 70ec841 into llvm:main Jun 19, 2024
7 checks passed

nico reviewed Jun 22, 2024

View reviewed changes

nico mentioned this pull request Jun 22, 2024

reapply [clang-doc] Add --asset option to clang-doc #96358

Merged

PeterChou1 mentioned this pull request Jun 24, 2024

[clang-doc] Remove stdexecpt from clang-doc test #96552

Merged

ilovepi pushed a commit that referenced this pull request Jun 25, 2024

[clang-doc] Remove stdexecpt from clang-doc test (#96552)

dbd5c78

Removes stdexecpt from clang-doc test introduced in #93928 since it violates the rule that test must be freestanding

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[clang-doc] Add basic e2e test #93928

[clang-doc] Add basic e2e test #93928

PeterChou1 commented May 31, 2024 •

edited

Loading

llvmbot commented May 31, 2024

ilovepi commented May 31, 2024

github-actions bot commented Jun 6, 2024 •

edited

Loading

ilovepi Jun 6, 2024

ilovepi left a comment •

edited

Loading

ilovepi commented Jun 6, 2024

ilovepi commented Jun 6, 2024

ilovepi left a comment •

edited

Loading

github-actions bot commented Jun 7, 2024 •

edited

Loading

ilovepi commented Jun 7, 2024

PeterChou1 commented Jun 7, 2024 •

edited

Loading

ilovepi left a comment

ilovepi Jun 7, 2024

ilovepi Jun 7, 2024

PeterChou1 Jun 8, 2024

petrhosek commented Jun 12, 2024

PeterChou1 commented Jun 12, 2024

PeterChou1 commented Jun 13, 2024

ilovepi Jun 13, 2024

ilovepi left a comment

ilovepi left a comment

ilovepi commented Jun 13, 2024

ilovepi commented Jun 13, 2024

nico Jun 22, 2024

nico Jun 22, 2024

bogner commented Jul 3, 2024

		// RUN: cp %S/Inputs/clang-doc-project1/*.h %t/clang-doc/include
		// RUN: cp %S/Inputs/clang-doc-project1/*.cpp %t/clang-doc/src

	"command": "clang++ -o Calculator.o -I../include $test_dir/src/Calculator.cpp",
	"command": "clang++ -o Calculator.o -I../include ../src/Calculator.cpp",

[clang-doc] Add basic e2e test #93928

[clang-doc] Add basic e2e test #93928

Conversation

PeterChou1 commented May 31, 2024 • edited Loading

llvmbot commented May 31, 2024

ilovepi commented May 31, 2024

github-actions bot commented Jun 6, 2024 • edited Loading

ilovepi Jun 6, 2024

Choose a reason for hiding this comment

ilovepi left a comment • edited Loading

Choose a reason for hiding this comment

ilovepi commented Jun 6, 2024

ilovepi commented Jun 6, 2024

ilovepi left a comment • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jun 7, 2024 • edited Loading

ilovepi commented Jun 7, 2024

PeterChou1 commented Jun 7, 2024 • edited Loading

ilovepi left a comment

Choose a reason for hiding this comment

ilovepi Jun 7, 2024

Choose a reason for hiding this comment

ilovepi Jun 7, 2024

Choose a reason for hiding this comment

PeterChou1 Jun 8, 2024

Choose a reason for hiding this comment

petrhosek commented Jun 12, 2024

PeterChou1 commented Jun 12, 2024

PeterChou1 commented Jun 13, 2024

ilovepi Jun 13, 2024

Choose a reason for hiding this comment

ilovepi left a comment

Choose a reason for hiding this comment

ilovepi left a comment

Choose a reason for hiding this comment

ilovepi commented Jun 13, 2024

ilovepi commented Jun 13, 2024

nico Jun 22, 2024

Choose a reason for hiding this comment

nico Jun 22, 2024

Choose a reason for hiding this comment

bogner commented Jul 3, 2024

PeterChou1 commented May 31, 2024 •

edited

Loading

github-actions bot commented Jun 6, 2024 •

edited

Loading

ilovepi left a comment •

edited

Loading

ilovepi left a comment •

edited

Loading

github-actions bot commented Jun 7, 2024 •

edited

Loading

PeterChou1 commented Jun 7, 2024 •

edited

Loading