llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang-tools-extra Author: None (PeterChou1) <details> <summary>Changes</summary> This patches adds more e2e test to clang-doc which tests the html and markdown output. I've made the following changes - Modified basic-project.test to also include the markdown output - Added namespace.cpp which test anonymous namespace and nested namespace generation - Added enum.cpp which test the enum output for clang-doc - Added advance-project test project which test nested namespace, templates, enums --- 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: - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/database_template.json (+22) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Array.h (+35) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Circle.h (+32) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Shape.h (+49) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/include/Utils.h (+38) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Array.cpp (+31) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Circle.cpp (+24) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Shape.cpp (+28) - (added) clang-tools-extra/test/clang-doc/Inputs/advance-project/src/Utils.cpp (+37) - (added) clang-tools-extra/test/clang-doc/advance-project.test (+701) - (modified) clang-tools-extra/test/clang-doc/basic-project.test (+137-22) - (added) clang-tools-extra/test/clang-doc/enum.cpp (+68) - (added) clang-tools-extra/test/clang-doc/namespace.cpp (+548) ``````````diff 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] `````````` </details> https://github.com/llvm/llvm-project/pull/97518 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
