[clang][tablegen] adds human documentation to `WarningOption`

[cjdb]

Summary

Building on D126796, this commit adds the infrastructure for being able
to print out descriptions of what each warning does.

[aaron.ballman]

Can you post some examples of the output from this option so we can see what the end results look like more easily?

[cjdb]

In D126832#3553569, @aaron.ballman wrote:

Can you post some examples of the output from this option so we can see what the end results look like more easily?

Right now this doesn't do anything at all, except feed the documentation from tablegen to Clang. It's just taking the text (represented by ...) from code Documentation [{...}], trimming any surrounding spaces, and putting that into DIAG_ENTRY.

e.g.

code Documentation [{
  Hello, world!

  Goodbye, world!
}]

would be forwarded as "Hello, world!\n\n Goodbye, world!"

[aaron.ballman]

In D126832#3554816, @cjdb wrote:

In D126832#3553569, @aaron.ballman wrote:

Can you post some examples of the output from this option so we can see what the end results look like more easily?

Right now this doesn't do anything at all, except feed the documentation from tablegen to Clang. It's just taking the text (represented by ...) from code Documentation [{...}], trimming any surrounding spaces, and putting that into DIAG_ENTRY.

e.g.

code Documentation [{
  Hello, world!

  Goodbye, world!
}]

would be forwarded as "Hello, world!\n\n Goodbye, world!"

Thanks, that helps me to visualize what's going on. Any thoughts on how we could test this functionality, or are we going to assume that the testing comes from its usage when we actually make use of the new information threaded in?

clang/lib/Basic/DiagnosticIDs.cpp

628

clang/utils/TableGen/ClangDiagnosticsEmitter.cpp

1550–1553

Isn't this functionally equivalent? (It means we're using a raw empty string rather than a normal empty string, but that shouldn't matter.)

[cjdb]

applies feedback

[cjdb]

In D126832#3567035, @aaron.ballman wrote:

In D126832#3554816, @cjdb wrote:

In D126832#3553569, @aaron.ballman wrote:

Can you post some examples of the output from this option so we can see what the end results look like more easily?

Right now this doesn't do anything at all, except feed the documentation from tablegen to Clang. It's just taking the text (represented by ...) from code Documentation [{...}], trimming any surrounding spaces, and putting that into DIAG_ENTRY.

e.g.

code Documentation [{
  Hello, world!

  Goodbye, world!
}]

would be forwarded as "Hello, world!\n\n Goodbye, world!"

Thanks, that helps me to visualize what's going on. Any thoughts on how we could test this functionality, or are we going to assume that the testing comes from its usage when we actually make use of the new information threaded in?

Good question. Unless this functionality already has tests (and I'm gathering it doesn't), I think we can rely on Clang being the test. (Though we should consider ourselves on notice for adding robust unit tests at some point.)

clang/utils/TableGen/ClangDiagnosticsEmitter.cpp

1550–1553

Wow, I can no longer say I've never done if (condition) return true; else return false; 😂

[aaron.ballman]

Good question. Unless this functionality already has tests (and I'm gathering it doesn't), I think we can rely on Clang being the test. (Though we should consider ourselves on notice for adding robust unit tests at some point.)

I don't know of tests for it, so I'm okay with that approach. LGTM!

clang/include/clang/Basic/DiagnosticCategories.h

 #define CATEGORY(X, ENUM) ENUM,
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef CATEGORY
 #undef GET_CATEGORY_TABLE
       DiagCat_NUM_CATEGORIES
     };
 
     enum class Group {
-#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups) GroupName,
+#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups, Docs)        \
+  GroupName,
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef CATEGORY
 #undef DIAG_ENTRY
     };
   }  // end namespace diag
 }  // end namespace clang
 
 #endif

clang/include/clang/Basic/DiagnosticIDs.h

public:
   ///
   static bool isBuiltinExtensionDiag(unsigned DiagID, bool &EnabledByDefault);
 
   /// Given a group ID, returns the flag that toggles the group.
   /// For example, for Group::DeprecatedDeclarations, returns
   /// "deprecated-declarations".
   static StringRef getWarningOptionForGroup(diag::Group);
 
+  /// Given a diagnostic group ID, return its documentation.
+  static StringRef getWarningOptionDocumentation(diag::Group GroupID);
+
   /// Given a group ID, returns the flag that toggles the group.
   /// For example, for "deprecated-declarations", returns
   /// Group::DeprecatedDeclarations.
   static llvm::Optional<diag::Group> getGroupForWarningOption(StringRef);
 
   /// Return the lowest-level group that contains the specified diagnostic.
   static llvm::Optional<diag::Group> getGroupForDiag(unsigned DiagID);
 

clang/lib/Basic/DiagnosticIDs.cpp

 #include "clang/Basic/DiagnosticGroups.inc"
 #undef GET_DIAG_ARRAYS
 
 namespace {
   struct WarningOption {
     uint16_t NameOffset;
     uint16_t Members;
     uint16_t SubGroups;
+    StringRef Documentation;
 
     // String is stored with a pascal-style length byte.
     StringRef getName() const {
       return StringRef(DiagGroupNames + NameOffset + 1,
                        DiagGroupNames[NameOffset]);
     }
   };
 }
 
 // Second the table of options, sorted by name for fast binary lookup.
 static const WarningOption OptionTable[] = {
-#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups)              \
-  {FlagNameOffset, Members, SubGroups},
+#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups, Docs)        \
+  {FlagNameOffset, Members, SubGroups, Docs},
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef DIAG_ENTRY
 };
 
+/// Given a diagnostic group ID, return its documentation.
+StringRef DiagnosticIDs::getWarningOptionDocumentation(diag::Group Group) {
+  return OptionTable[static_cast<int>(Group)].Documentation;
+}
+
 StringRef DiagnosticIDs::getWarningOptionForGroup(diag::Group Group) {
   return OptionTable[static_cast<int>(Group)].getName();
 }
 
 llvm::Optional<diag::Group>
 DiagnosticIDs::getGroupForWarningOption(StringRef Name) {
   const auto *Found = llvm::partition_point(
       OptionTable, [=](const WarningOption &O) { return O.getName() < Name; });

clang/tools/diagtool/DiagnosticNames.cpp

 
 
 #define GET_DIAG_ARRAYS
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef GET_DIAG_ARRAYS
 
 // Second the table of options, sorted by name for fast binary lookup.
 static const GroupRecord OptionTable[] = {
-#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups)              \
+#define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups, Docs)        \
   {FlagNameOffset, Members, SubGroups},
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef DIAG_ENTRY
 };
 
 llvm::StringRef GroupRecord::getName() const {
   return StringRef(DiagGroupNames + NameOffset + 1, DiagGroupNames[NameOffset]);
 }

clang/utils/TableGen/ClangDiagnosticsEmitter.cpp

if (hasDiags) {
       OS << "0, ";
     }
 
     // Subgroups.
     const std::vector<std::string> &SubGroups = I.second.SubGroups;
     const bool hasSubGroups =
         !SubGroups.empty() || (IsPedantic && !GroupsInPedantic.empty());
     if (hasSubGroups) {
-      OS << "/* DiagSubGroup" << I.second.IDNo << " */ " << SubGroupIndex;
+      OS << "/* DiagSubGroup" << I.second.IDNo << " */ " << SubGroupIndex
+         << ", ";
       if (IsPedantic)
         SubGroupIndex += GroupsInPedantic.size();
       SubGroupIndex += SubGroups.size() + 1;
     } else {
-      OS << "0";
+      OS << "0, ";
     }
 
+    std::string Documentation = I.second.Defs.back()
+                                    ->getValue("Documentation")
+                                    ->getValue()
+                                    ->getAsUnquotedString();
+
+    OS << "R\"(" << StringRef(Documentation).trim() << ")\"";
+
     OS << ")\n";
   }
   OS << "#endif // DIAG_ENTRY\n\n";
 }
 
 /// Emit the table of diagnostic categories.
 ///
 /// The table has the form of macro calls that have two parameters. The
 /// category's name as well as an enum that represents the category. The