https://github.com/shiltian created https://github.com/llvm/llvm-project/pull/183938
The builtin documentation emitter previously sorted all categories purely alphabetically, which placed the "Undocumented" section before categories like "WMMA" in the generated RST. This made the output confusing since stub entries appeared before real documentation. Push the "Undocumented" category to the end of the output so that all documented categories appear first, regardless of their names. >From f8f8d5a43d17a4dd77f991cbf9e25426da78b2f6 Mon Sep 17 00:00:00 2001 From: Shilei Tian <[email protected]> Date: Sat, 28 Feb 2026 14:16:08 -0500 Subject: [PATCH] [Clang][TableGen] Sort undocumented builtins after documented ones in generated docs The builtin documentation emitter previously sorted all categories purely alphabetically, which placed the "Undocumented" section before categories like "WMMA" in the generated RST. This made the output confusing since stub entries appeared before real documentation. Push the "Undocumented" category to the end of the output so that all documented categories appear first, regardless of their names. --- clang/test/TableGen/builtin-docs.td | 30 ++++++++++++------- clang/utils/TableGen/ClangBuiltinsEmitter.cpp | 13 ++++++-- 2 files changed, 30 insertions(+), 13 deletions(-) diff --git a/clang/test/TableGen/builtin-docs.td b/clang/test/TableGen/builtin-docs.td index 99de9767575d1..468268de4e6c6 100644 --- a/clang/test/TableGen/builtin-docs.td +++ b/clang/test/TableGen/builtin-docs.td @@ -1,6 +1,16 @@ // RUN: clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - 2>&1 | \ // RUN: FileCheck %s +// Test that the Undocumented category always sorts after all documented +// categories, even when its name would come earlier alphabetically (e.g. +// "Undocumented" < "Work-Item Builtins"). +// RUN: clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - 2>&1 | \ +// RUN: FileCheck --check-prefix=CAT-ORDER %s +// CAT-ORDER: ABI Builtins +// CAT-ORDER: Instruction Builtins +// CAT-ORDER: Work-Item Builtins +// CAT-ORDER: Undocumented + // Test that mismatched ArgNames count produces an error. // RUN: not clang-tblgen -gen-builtin-docs -I%p/../../include %s -o - \ // RUN: -DERROR_ARGNAMES_MISMATCH 2>&1 | \ @@ -226,7 +236,16 @@ def __builtin_test_no_doc : TestBuiltin<"int(int, int)">; // CHECK: void __builtin_test_store(int val, int address_space<1> * ptr) // CHECK: Stores a value to the given global memory pointer. -// --- Undocumented (alphabetically between Instruction and Work-Item) --- +// --- Work-Item Builtins (inline doc, no ArgNames) --- +// CHECK: Work-Item Builtins +// CHECK-NEXT: ================== +// CHECK: These builtins return work-item identification. +// CHECK: ``__builtin_test_workitem_id_x`` +// CHECK: unsigned int __builtin_test_workitem_id_x() +// CHECK: **Target Features:** some-feature +// CHECK: Returns the work-item id in the x dimension. + +// --- Undocumented (sorted last, after all documented categories) --- // CHECK: Undocumented // CHECK-NEXT: ============ @@ -239,15 +258,6 @@ def __builtin_test_no_doc : TestBuiltin<"int(int, int)">; // CHECK: void __builtin_test_undocumented() // CHECK: No documentation. -// --- Work-Item Builtins (inline doc, no ArgNames) --- -// CHECK: Work-Item Builtins -// CHECK-NEXT: ================== -// CHECK: These builtins return work-item identification. -// CHECK: ``__builtin_test_workitem_id_x`` -// CHECK: unsigned int __builtin_test_workitem_id_x() -// CHECK: **Target Features:** some-feature -// CHECK: Returns the work-item id in the x dimension. - //===----------------------------------------------------------------------===// // Error test: ArgNames count mismatch //===----------------------------------------------------------------------===// diff --git a/clang/utils/TableGen/ClangBuiltinsEmitter.cpp b/clang/utils/TableGen/ClangBuiltinsEmitter.cpp index f381d6dce6261..f628a993a23cc 100644 --- a/clang/utils/TableGen/ClangBuiltinsEmitter.cpp +++ b/clang/utils/TableGen/ClangBuiltinsEmitter.cpp @@ -769,10 +769,17 @@ void clang::EmitClangBuiltinDocs(const RecordKeeper &Records, raw_ostream &OS) { } } - // Sort categories alphabetically by name for deterministic output. + // Sort categories alphabetically by name for deterministic output, but + // push the "Undocumented" category to the end so that documented sections + // always appear first. llvm::sort(SplitDocs, [](const auto &A, const auto &B) { - return A.first->getValueAsString("Name") < - B.first->getValueAsString("Name"); + StringRef NameA = A.first->getValueAsString("Name"); + StringRef NameB = B.first->getValueAsString("Name"); + bool UndocA = (NameA == "Undocumented"); + bool UndocB = (NameB == "Undocumented"); + if (UndocA != UndocB) + return UndocB; + return NameA < NameB; }); // Write out each category and its builtins. _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
