llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang Author: Shilei Tian (shiltian) <details> <summary>Changes</summary> 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. --- Full diff: https://github.com/llvm/llvm-project/pull/183938.diff 2 Files Affected: - (modified) clang/test/TableGen/builtin-docs.td (+20-10) - (modified) clang/utils/TableGen/ClangBuiltinsEmitter.cpp (+10-3) ``````````diff 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. `````````` </details> https://github.com/llvm/llvm-project/pull/183938 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
