Fix capability generator to sort capabilities alphabetically within header groups (#7851)

* Fix capability generator to sort capabilities alphabetically within header groups

The slang-capability-generator now sorts capabilities alphabetically by name
within each header group in the generated a3-02-reference-capability-atoms.md
documentation file. This ensures consistent ordering for better readability
and organization.

Fixes #5030

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: aidanfnv <aidanfnv@users.noreply.github.com>

* Regenerate capability atoms documentation with alphabetical sorting

The capability generator now sorts capabilities alphabetically within
each header group. This commit includes the regenerated documentation
file to demonstrate the alphabetical sorting functionality implemented
in the generator code.

Generated with updated capability generator that sorts capabilities
within groups: Targets, Stages, Versions, Extensions, Compound
Capabilities, and Other.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* format code (#7853)

Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: aidanfnv <aidanfnv@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: slangbot <ellieh+slangbot@nvidia.com>
Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

1 files changed, 29 insertions, 1 deletions

diff --git a/tools/slang-capability-generator/capability-generator-main.cpp b/tools/slang-capability-generator/capability-generator-main.cpp
index 56b615330..7b7800295 100644
--- a/tools/slang-capability-generator/capability-generator-main.cpp
+++ b/tools/slang-capability-generator/capability-generator-main.cpp
@@ -1063,10 +1063,38 @@ SlangResult generateDocumentation(
     setupDocumentationHeader(sbDoc, outPath);
 
     List<StringBuilder> sbDocSections = setupDocCommentHeaderStringBuilders();
+
+    // Group capabilities by header group and sort alphabetically within each group
+    List<List<RefPtr<CapabilityDef>>> capabilitiesByHeaderGroup;
+    capabilitiesByHeaderGroup.setCount((UInt)AutoDocHeaderGroup::Count);
+
+    // Collect capabilities into their respective header groups
     for (auto def : defs)
     {
-        printDocForCapabilityDef(sbDoc, def, sbDocSections);
+        if (!isInternalDef(def) && def->flavor != CapabilityFlavor::Abstract &&
+            def->docComment.headerGroup != AutoDocHeaderGroup::Invalid)
+        {
+            capabilitiesByHeaderGroup[(UInt)def->docComment.headerGroup].add(def);
+        }
+    }
+
+    // Sort capabilities within each header group alphabetically by name
+    for (auto& capabilitiesInGroup : capabilitiesByHeaderGroup)
+    {
+        capabilitiesInGroup.sort([](const RefPtr<CapabilityDef>& a, const RefPtr<CapabilityDef>& b)
+                                 { return a->name < b->name; });
     }
+
+    // Add sorted capabilities to documentation sections
+    for (UInt headerGroupIndex = 0; headerGroupIndex < (UInt)AutoDocHeaderGroup::Count;
+         headerGroupIndex++)
+    {
+        for (auto def : capabilitiesByHeaderGroup[headerGroupIndex])
+        {
+            printDocForCapabilityDef(sbDoc, def, sbDocSections);
+        }
+    }
+
     for (auto stringBuilder : sbDocSections)
         sbDoc << stringBuilder.toString();
     return 1;