Sort Attributes by "HeaderName"

[erichkeane]

Summary

Attributes in the docs were previously sorted (apparently)
by the attribute name, so AnyX86Interrupt ended up being the
first one, rather than in a meaningful place. This resulted in the
4 'interrupt' titled sections being all in different places.

This replaces it with a naive alphabetical sort (case sensitive, underscore
and special characters first, etc).

[erichkeane]

Additionally, I'm going to edit the 'interrupt' docs in a separate commit to give each a separate header name based on the architecture. Currently they are all named 'interrupt', so I want to rename them all interrupt (x86), etc. Look for a future review!

utils/TableGen/ClangAttrEmitter.cpp

3666 ↗

(On Diff #119192)

These two cannot be 'const', otherwise operator= is suppressed. Thus, std::sort won't work (Requires ValueSwappable).

3865 ↗

(On Diff #119192)

Had to remove const, since the sort actually modifies the map.

[erichkeane]

utils/TableGen/ClangAttrEmitter.cpp

3670 ↗

(On Diff #119192)

Craig brought up that I could just take by value and move out of 'first', which is more flexible for usage. New patch incoming once it passes a build.

[erichkeane]

Change the constructor in DocumentationData to take by value.

[aaron.ballman]

LGTM, thank you!

cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp

void EmitClangAttrSubjectMatchRulesParserStringSwitches(RecordKeeper &Records,
                                                         raw_ostream &OS) {
   getPragmaAttributeSupport(Records).generateParsingHelpers(OS);
 }
 
 class DocumentationData {
 public:
   const Record *Documentation;
   const Record *Attribute;
+  std::string Heading;
+  unsigned SupportedSpellings;
 
-  DocumentationData(const Record &Documentation, const Record &Attribute)
-      : Documentation(&Documentation), Attribute(&Attribute) {}
+  DocumentationData(const Record &Documentation, const Record &Attribute,
+                    const std::pair<std::string, unsigned> HeadingAndKinds)
+      : Documentation(&Documentation), Attribute(&Attribute),
+        Heading(std::move(HeadingAndKinds.first)),
+        SupportedSpellings(HeadingAndKinds.second) {}
 };
 
 static void WriteCategoryHeader(const Record *DocCategory,
                                 raw_ostream &OS) {
   const std::string &Name = DocCategory->getValueAsString("Name");
   OS << Name << "\n" << std::string(Name.length(), '=') << "\n";
 
   // If there is content, print that as well.
enum SpellingKind {
   CXX11 = 1 << 1,
   C2x = 1 << 2,
   Declspec = 1 << 3,
   Microsoft = 1 << 4,
   Keyword = 1 << 5,
   Pragma = 1 << 6
 };
 
-static void WriteDocumentation(RecordKeeper &Records,
-                               const DocumentationData &Doc, raw_ostream &OS) {
+static std::pair<std::string, unsigned>
+GetAttributeHeadingAndSpellingKinds(const Record &Documentation,
+                                    const Record &Attribute) {
   // FIXME: there is no way to have a per-spelling category for the attribute
   // documentation. This may not be a limiting factor since the spellings
   // should generally be consistently applied across the category.
 
-  std::vector<FlattenedSpelling> Spellings = GetFlattenedSpellings(*Doc.Attribute);
+  std::vector<FlattenedSpelling> Spellings = GetFlattenedSpellings(Attribute);
 
   // Determine the heading to be used for this attribute.
-  std::string Heading = Doc.Documentation->getValueAsString("Heading");
+  std::string Heading = Documentation.getValueAsString("Heading");
   bool CustomHeading = !Heading.empty();
   if (Heading.empty()) {
     // If there's only one spelling, we can simply use that.
     if (Spellings.size() == 1)
       Heading = Spellings.begin()->name();
     else {
       std::set<std::string> Uniques;
       for (auto I = Spellings.begin(), E = Spellings.end();
            I != E && Uniques.size() <= 1; ++I) {
         std::string Spelling = NormalizeNameForSpellingComparison(I->name());
         Uniques.insert(Spelling);
       }
       // If the semantic map has only one spelling, that is sufficient for our
       // needs.
       if (Uniques.size() == 1)
         Heading = *Uniques.begin();
     }
   }
 
   // If the heading is still empty, it is an error.
   if (Heading.empty())
-    PrintFatalError(Doc.Attribute->getLoc(),
+    PrintFatalError(Attribute.getLoc(),
                     "This attribute requires a heading to be specified");
 
   // Gather a list of unique spellings; this is not the same as the semantic
   // spelling for the attribute. Variations in underscores and other non-
   // semantic characters are still acceptable.
   std::vector<std::string> Names;
 
   unsigned SupportedSpellings = 0;
if (!CustomHeading && !Names.empty()) {
     Heading += " (";
     for (auto I = Names.begin(), E = Names.end(); I != E; ++I) {
       if (I != Names.begin())
         Heading += ", ";
       Heading += *I;
     }
     Heading += ")";
   }
-  OS << Heading << "\n" << std::string(Heading.length(), '-') << "\n";
-
   if (!SupportedSpellings)
-    PrintFatalError(Doc.Attribute->getLoc(),
+    PrintFatalError(Attribute.getLoc(),
                     "Attribute has no supported spellings; cannot be "
                     "documented");
+  return std::make_pair(std::move(Heading), SupportedSpellings);
+}
+
+static void WriteDocumentation(RecordKeeper &Records,
+                               const DocumentationData &Doc, raw_ostream &OS) {
+  OS << Doc.Heading << "\n" << std::string(Doc.Heading.length(), '-') << "\n";
 
   // List what spelling syntaxes the attribute supports.
   OS << ".. csv-table:: Supported Syntaxes\n";
   OS << "   :header: \"GNU\", \"C++11\", \"C2x\", \"__declspec\", \"Keyword\",";
   OS << " \"Pragma\", \"Pragma clang attribute\"\n\n";
   OS << "   \"";
-  if (SupportedSpellings & GNU) OS << "X";
+  if (Doc.SupportedSpellings & GNU) OS << "X";
   OS << "\",\"";
-  if (SupportedSpellings & CXX11) OS << "X";
+  if (Doc.SupportedSpellings & CXX11) OS << "X";
   OS << "\",\"";
-  if (SupportedSpellings & C2x) OS << "X";
+  if (Doc.SupportedSpellings & C2x) OS << "X";
   OS << "\",\"";
-  if (SupportedSpellings & Declspec) OS << "X";
+  if (Doc.SupportedSpellings & Declspec) OS << "X";
   OS << "\",\"";
-  if (SupportedSpellings & Keyword) OS << "X";
+  if (Doc.SupportedSpellings & Keyword) OS << "X";
   OS << "\", \"";
-  if (SupportedSpellings & Pragma) OS << "X";
+  if (Doc.SupportedSpellings & Pragma) OS << "X";
   OS << "\", \"";
   if (getPragmaAttributeSupport(Records).isAttributedSupported(*Doc.Attribute))
     OS << "X";
   OS << "\"\n\n";
 
   // If the attribute is deprecated, print a message about it, and possibly
   // provide a replacement attribute.
   if (!Doc.Documentation->isValueUnset("Deprecated")) {
for (const auto *D : Docs) {
       // If the category is "undocumented", then there cannot be any other
       // documentation categories (otherwise, the attribute would become
       // documented).
       std::string Cat = Category->getValueAsString("Name");
       bool Undocumented = Cat == "Undocumented";
       if (Undocumented && Docs.size() > 1)
         PrintFatalError(Doc.getLoc(),
                         "Attribute is \"Undocumented\", but has multiple "
-                        "documentation categories");      
+                        "documentation categories");
 
       if (!Undocumented)
-        SplitDocs[Category].push_back(DocumentationData(Doc, Attr));
+        SplitDocs[Category].push_back(DocumentationData(
+            Doc, Attr, GetAttributeHeadingAndSpellingKinds(Doc, Attr)));
     }
   }
 
   // Having split the attributes out based on what documentation goes where,
   // we can begin to generate sections of documentation.
-  for (const auto &I : SplitDocs) {
+  for (auto &I : SplitDocs) {
     WriteCategoryHeader(I.first, OS);
 
+    std::sort(I.second.begin(), I.second.end(),
+              [](const DocumentationData &D1, const DocumentationData &D2) {
+                return D1.Heading < D2.Heading;
+              });
+
     // Walk over each of the attributes in the category and write out their
     // documentation.
     for (const auto &Doc : I.second)
       WriteDocumentation(Records, Doc, OS);
   }
 }
 
 void EmitTestPragmaAttributeSupportedAttributes(RecordKeeper &Records,