[Clang][Docs] Consolidate option hiding in ClangOptionDocEmitter

[bogner]

Summary

Update the hasFlag check to account for an Option's groups to better
match how the option parsing logic works, and instead of checking if a
group has include/exclude flags just check if there are any visible
options in it.

This cleans up some the empty sections that are currently emitted in
clang's option docs.

[MaskRay]

clang/utils/TableGen/ClangOptionDocEmitter.cpp

43

For new functions, consider using static for internal linkage functions even if they are surrounded by an anonymous namespace, per https://llvm.org/docs/CodingStandards.html#anonymous-namespaces

[MaskRay]

The diff of docs-clang-html output is preferable:)

--- tools/clang/docs/html/ClangCommandLineReference.html.old    2023-08-12 22:09:58.900516809 -0700
+++ tools/clang/docs/html/ClangCommandLineReference.html        2023-08-12 22:10:23.876913374 -0700
@@ -94,18 +94,8 @@
 <li><p><a class="reference internal" href="#static-analyzer-options" id="id37">Static analyzer options</a></p></li>
 <li><p><a class="reference internal" href="#fortran-compilation-options" id="id38">Fortran compilation options</a></p></li>
 <li><p><a class="reference internal" href="#linker-options" id="id39">Linker options</a></p></li>
-<li><p><a class="reference internal" href="#clang-cl-options" id="id40">&lt;clang-cl options&gt;</a></p>
-<ul>
-<li><p><a class="reference internal" href="#clang-cl-compile-only-options" id="id41">&lt;clang-cl compile-only options&gt;</a></p>
-<ul>
-<li><p><a class="reference internal" href="#m-group" id="id42">&lt;/M group&gt;</a></p></li>
-<li><p><a class="reference internal" href="#volatile-group" id="id43">&lt;/volatile group&gt;</a></p></li>
-</ul>
-</li>
-<li><p><a class="reference internal" href="#clang-cl-ignored-options" id="id44">&lt;clang-cl ignored options&gt;</a></p></li>
-</ul>
-</li>
-<li><p><a class="reference internal" href="#clang-dxc-options" id="id45">&lt;clang-dxc options&gt;</a></p></li>
+<li><p><a class="reference internal" href="#clang-cl-options" id="id40">&lt;clang-cl options&gt;</a></p></li>
+<li><p><a class="reference internal" href="#clang-dxc-options" id="id41">&lt;clang-dxc options&gt;</a></p></li>
 </ul>
 </nav>
 <section id="introduction">
@@ -7878,21 +7868,9 @@
 <dd></dd></dl>

 <p>Set multiple /O flags at once; e.g. ‘/O2y-’ for ‘/O2 /Oy-’</p>
-<section id="clang-cl-compile-only-options">
-<h3><a class="toc-backref" href="#id41" role="doc-backlink">&lt;clang-cl compile-only options&gt;</a><a class="headerlink" href="#clang-cl-compile-only-options" title="Permalink to this heading">¶</a></h3>
-<section id="m-group">
-<h4><a class="toc-backref" href="#id42" role="doc-backlink">&lt;/M group&gt;</a><a class="headerlink" href="#m-group" title="Permalink to this heading">¶</a></h4>
-</section>
-<section id="volatile-group">
-<h4><a class="toc-backref" href="#id43" role="doc-backlink">&lt;/volatile group&gt;</a><a class="headerlink" href="#volatile-group" title="Permalink to this heading">¶</a></h4>
-</section>
-</section>
-<section id="clang-cl-ignored-options">
-<h3><a class="toc-backref" href="#id44" role="doc-backlink">&lt;clang-cl ignored options&gt;</a><a class="headerlink" href="#clang-cl-ignored-options" title="Permalink to this heading">¶</a></h3>
-</section>
 </section>
 <section id="clang-dxc-options">
-<h2><a class="toc-backref" href="#id45" role="doc-backlink">&lt;clang-dxc options&gt;</a><a class="headerlink" href="#clang-dxc-options" title="Permalink to this heading">¶</a></h2>
+<h2><a class="toc-backref" href="#id41" role="doc-backlink">&lt;clang-dxc options&gt;</a><a class="headerlink" href="#clang-dxc-options" title="Permalink to this heading">¶</a></h2>
 <p>dxc compatibility options</p>
 <dl class="std option">
 <dt class="sig sig-object std" id="cmdoption-clang5-E-arg">

clang/utils/TableGen/ClangOptionDocEmitter.cpp

 struct DocumentedOption {
   Record *Option;
   std::vector<Record*> Aliases;
 };
 struct DocumentedGroup;
 struct Documentation {
   std::vector<DocumentedGroup> Groups;
   std::vector<DocumentedOption> Options;
+
+  bool empty() {
+    return Groups.empty() && Options.empty();
+  }
 };
 struct DocumentedGroup : Documentation {
   Record *Group;
 };
 
+static bool hasFlag(const Record *Option, StringRef OptionFlag) {
+  for (const Record *Flag : Option->getValueAsListOfDefs("Flags"))
+    if (Flag->getName() == OptionFlag)
+      return true;
+  if (const DefInit *DI = dyn_cast<DefInit>(Option->getValueInit("Group")))
+    for (const Record *Flag : DI->getDef()->getValueAsListOfDefs("Flags"))
+      if (Flag->getName() == OptionFlag)
+        return true;
+  return false;
+}
+
+static bool isOptionVisible(const Record *Option, const Record *DocInfo) {
+  for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags"))
+    if (hasFlag(Option, Exclusion))
+      return false;
+  if (!DocInfo->getValue("IncludedFlags"))
+    return true;
+  for (StringRef Inclusion : DocInfo->getValueAsListOfStrings("IncludedFlags"))
+    if (hasFlag(Option, Inclusion))
+      return true;
+  return false;
+}
+
 // Reorganize the records into a suitable form for emitting documentation.
-Documentation extractDocumentation(RecordKeeper &Records) {
+Documentation extractDocumentation(RecordKeeper &Records,
+                                   const Record *DocInfo) {
   Documentation Result;
 
   // Build the tree of groups. The root in the tree is the fake option group
   // (Record*)nullptr, which contains all top-level groups and options.
   std::map<Record*, std::vector<Record*> > OptionsInGroup;
   std::map<Record*, std::vector<Record*> > GroupsInGroup;
   std::map<Record*, std::vector<Record*> > Aliases;
 
std::function<Documentation(Record *)> DocumentationForGroup =
 
     auto &Groups = GroupsInGroup[R];
     llvm::sort(Groups, CompareByLocation);
     for (Record *G : Groups) {
       D.Groups.emplace_back();
       D.Groups.back().Group = G;
       Documentation &Base = D.Groups.back();
       Base = DocumentationForGroup(G);
+      if (Base.empty())
+        D.Groups.pop_back();
     }
 
     auto &Options = OptionsInGroup[R];
     llvm::sort(Options, CompareByName);
     for (Record *O : Options)
+      if (isOptionVisible(O, DocInfo))
         D.Options.push_back(DocumentationForOption(O));
 
     return D;
   };
 
   return DocumentationForGroup(nullptr);
 }
 
 // Get the first and successive separators to use for an OptionKind.
return StringSwitch<unsigned>(OptionKind->getName())
     .Cases("KIND_JOINED", "KIND_JOINED_OR_SEPARATE", "KIND_SEPARATE", 1)
     .Cases("KIND_REMAINING_ARGS", "KIND_REMAINING_ARGS_JOINED",
            "KIND_COMMAJOINED", UnlimitedArgs)
     .Case("KIND_JOINED_AND_SEPARATE", 2)
     .Case("KIND_MULTIARG", Option->getValueAsInt("NumArgs"))
     .Default(0);
 }
 
-bool hasFlag(const Record *OptionOrGroup, StringRef OptionFlag) {
-  for (const Record *Flag : OptionOrGroup->getValueAsListOfDefs("Flags"))
-    if (Flag->getName() == OptionFlag)
-      return true;
-  return false;
-}
-
-bool isIncluded(const Record *OptionOrGroup, const Record *DocInfo) {
-  assert(DocInfo->getValue("IncludedFlags") && "Missing includeFlags");
-  for (StringRef Inclusion : DocInfo->getValueAsListOfStrings("IncludedFlags"))
-    if (hasFlag(OptionOrGroup, Inclusion))
-      return true;
-  return false;
-}
-
-bool isGroupIncluded(const DocumentedGroup &Group, const Record *DocInfo) {
-  if (isIncluded(Group.Group, DocInfo))
-    return true;
-  for (auto &O : Group.Options)
-    if (isIncluded(O.Option, DocInfo))
-      return true;
-  for (auto &G : Group.Groups) {
-    if (isIncluded(G.Group, DocInfo))
-      return true;
-    if (isGroupIncluded(G, DocInfo))
-      return true;
-  }
-  return false;
-}
-
-bool isExcluded(const Record *OptionOrGroup, const Record *DocInfo) {
-  // FIXME: Provide a flag to specify the set of exclusions.
-  for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags"))
-    if (hasFlag(OptionOrGroup, Exclusion))
-      return true;
-  return false;
-}
-
 std::string escapeRST(StringRef Str) {
   std::string Out;
   for (auto K : Str) {
     if (StringRef("`*|_[]\\").count(K))
       Out.push_back('\\');
     Out.push_back(K);
   }
   return Out;

 }
 
 template <typename Fn>
 void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
                        Fn F) {
   F(Option.Option);
 
   for (auto *Alias : Option.Aliases)
-    if (!isExcluded(Alias, DocInfo) && canSphinxCopeWithOption(Option.Option))
+    if (isOptionVisible(Alias, DocInfo) &&
+        canSphinxCopeWithOption(Option.Option))
       F(Alias);
 }
 
 void emitOption(const DocumentedOption &Option, const Record *DocInfo,
                 raw_ostream &OS) {
-  if (isExcluded(Option.Option, DocInfo))
-    return;
-  if (DocInfo->getValue("IncludedFlags") && !isIncluded(Option.Option, DocInfo))
-    return;
   if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" ||
       Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT")
     return;
   if (!canSphinxCopeWithOption(Option.Option))
     return;
 
   // HACK: Emit a different program name with each option to work around
   // sphinx's inability to cope with options that differ only by punctuation
if (!Description.empty())
     OS << Description << "\n\n";
 }
 
 void emitDocumentation(int Depth, const Documentation &Doc,
                        const Record *DocInfo, raw_ostream &OS);
 
 void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
                raw_ostream &OS) {
-  if (isExcluded(Group.Group, DocInfo))
-    return;
-
-  if (DocInfo->getValue("IncludedFlags") && !isGroupIncluded(Group, DocInfo))
-    return;
-
   emitHeading(Depth,
               getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS);
 
   // Emit the description, if we have one.
   std::string Description =
       getRSTStringWithTextFallback(Group.Group, "DocBrief", "HelpText");
   if (!Description.empty())
     OS << Description << "\n\n";
void clang::EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) {
   if (!DocInfo) {
     PrintFatalError("The GlobalDocumentation top-level definition is missing, "
                     "no documentation will be generated.");
     return;
   }
   OS << DocInfo->getValueAsString("Intro") << "\n";
   OS << ".. program:: " << DocInfo->getValueAsString("Program") << "\n";
 
-  emitDocumentation(0, extractDocumentation(Records), DocInfo, OS);
+  emitDocumentation(0, extractDocumentation(Records, DocInfo), DocInfo, OS);
 }