[PATCH] D156436: [llvm/OptTable] Print options without documentation

[Jan Ole Hüser via Phabricator via llvm-commits]

j0le created this revision.
j0le added reviewers: serge-sans-paille, MaskRay, bogner.
Herald added a subscriber: hiraditya.
Herald added a project: All.
j0le requested review of this revision.
Herald added subscribers: llvm-commits, wangpc.
Herald added a project: LLVM.

When printing the help (most likely triggered by the tool’s option
"--help"), then list also those options, that don’t have a
documentation, i.e. no help text.  That makes those options more
discoverable.  The user is then able to search online, for example in an
alternate, non-official documentation, for example in the GCC or MSVC
documentaion in case of Clang.

An example of an option without help text is Clang’s option "-static",
which is well established, but couldn’t be found previously in the help
output.

If we want to hide specific options without help text, we should flag
them with llvm::opt::DriverFlag::HelpHidden, instead of relying on them
being hidden, because they have no help text.

With these changes:

  $ ./clang.exe --help | wc -l
  2451
  
  $ ./clang.exe --help-hidden | wc -l
  2556


Without these changes (on commit 2854852f4f0f <https://reviews.llvm.org/rG2854852f4f0f1fbb8fa7adb031f921898c8201d6>):

  $ ./clang.exe --help | wc -l
  1358
  
  $ ./clang.exe --help-hidden | wc -l
  1427



Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D156436

Files:
  llvm/include/llvm/Option/OptTable.h
  llvm/lib/Option/OptTable.cpp


Index: llvm/lib/Option/OptTable.cpp
===================================================================
--- llvm/lib/Option/OptTable.cpp
+++ llvm/lib/Option/OptTable.cpp
@@ -598,6 +598,11 @@
     int Pad = OptionFieldWidth - int(Option.size());
     OS.indent(InitialPad) << Option;
 
+    if (Opt.HelpText.empty()) {
+      OS << '\n';
+      continue;
+    }
+
     // Break on long option names.
     if (Pad < 0) {
       OS << "\n";
@@ -643,7 +648,9 @@
 
   for (unsigned Id = 1, e = getNumOptions() + 1; Id != e; ++Id) {
     // FIXME: Split out option groups.
-    if (getOptionKind(Id) == Option::GroupClass)
+    auto Kind = getOptionKind(Id);
+    if (Kind == Option::GroupClass || Kind == Option::InputClass ||
+        Kind == Option::UnknownClass)
       continue;
 
     unsigned Flags = getInfo(Id).Flags;
@@ -655,17 +662,18 @@
     // If an alias doesn't have a help text, show a help text for the aliased
     // option instead.
     const char *HelpText = getOptionHelpText(Id);
-    if (!HelpText && ShowAllAliases) {
+    if (!HelpText) {
       const Option Alias = getOption(Id).getAlias();
-      if (Alias.isValid())
+      if (Alias.isValid()) {
+        if (!ShowAllAliases)
+          continue;
         HelpText = getOptionHelpText(Alias.getID());
+      }
     }
 
-    if (HelpText && (strlen(HelpText) != 0)) {
-      const char *HelpGroup = getOptionHelpGroup(*this, Id);
-      const std::string &OptName = getOptionHelpName(*this, Id);
-      GroupedOptionHelp[HelpGroup].push_back({OptName, HelpText});
-    }
+    const char *HelpGroup = getOptionHelpGroup(*this, Id);
+    const std::string &OptName = getOptionHelpName(*this, Id);
+    GroupedOptionHelp[HelpGroup].push_back({OptName, HelpText});
   }
 
   for (auto& OptionGroup : GroupedOptionHelp) {
Index: llvm/include/llvm/Option/OptTable.h
===================================================================
--- llvm/include/llvm/Option/OptTable.h
+++ llvm/include/llvm/Option/OptTable.h
@@ -248,7 +248,8 @@
                          StringSaver &Saver,
                          function_ref<void(StringRef)> ErrorFn) const;
 
-  /// Render the help text for an option table.
+  /// Render the help text for an option table. Render options with and without
+  /// help texts.
   ///
   /// \param OS - The stream to write the help text to.
   /// \param Usage - USAGE: Usage
@@ -256,10 +257,8 @@
   /// \param FlagsToInclude - If non-zero, only include options with any
   ///                         of these flags set.
   /// \param FlagsToExclude - Exclude options with any of these flags set.
-  /// \param ShowAllAliases - If true, display all options including aliases
-  ///                         that don't have help texts. By default, we display
-  ///                         only options that are not hidden and have help
-  ///                         texts.
+  /// \param ShowAllAliases - If false, hide aliases, that do not have their
+  ///                         own help text.
   void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
                  unsigned FlagsToInclude, unsigned FlagsToExclude,
                  bool ShowAllAliases) const;


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D156436.544768.patch
Type: text/x-patch
Size: 3179 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20230727/10392a29/attachment.bin>