[CommandLine] Do not print empty categories with '--help-hidden'

[igorkudrin]

If a category has no options associated with it, the --help-hidden command still shows that category with the annotation "This option category has no options", and this is how it was implemented from the beginning when the categories were introduced, see commit 0537a98. A feature to hide unrelated options was added later, in https://reviews.llvm.org/D7100. Now, if a tool needs to hide unrelated options that are associated with categories, leaving some of them empty, those categories will still be visible on the --help-hidden output, even if they have no use for the tool; see the changes in llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test for an example.

The patch ensures that only categories with options are shown on both main and hidden help output.

[llvmbot]

@llvm/pr-subscribers-debuginfo

@llvm/pr-subscribers-llvm-support

Author: Igor Kudrin (igorkudrin)

Changes

If a category has no options associated with it, the --help-hidden command still shows that category with the annotation "This option category has no options", and this is how it was implemented from the beginning when the categories were introduced, see commit 0537a98. A feature to hide unrelated options was added later, in https://reviews.llvm.org/D7100. Now, if a tool needs to hide unrelated options that are associated with categories, leaving some of them empty, those categories will still be visible on the --help-hidden output, even if they have no use for the tool; see the changes in llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test for an example.

The patch ensures that only categories with options are shown on both main and hidden help output.

---

Full diff: https://github.com/llvm/llvm-project/pull/77043.diff

4 Files Affected:

• (modified) llvm/docs/CommandLine.rst (+1-2)
• (modified) llvm/lib/Support/CommandLine.cpp (+1-8)
• (modified) llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test (-4)
• (modified) llvm/unittests/Support/CommandLineTest.cpp (+25)

diff --git a/llvm/docs/CommandLine.rst b/llvm/docs/CommandLine.rst
index 3784db29ed8747..00d098745f55b8 100644
--- a/llvm/docs/CommandLine.rst
+++ b/llvm/docs/CommandLine.rst
@@ -1521,8 +1521,7 @@ passed to the constructor as ``const char*``.
 Note that declaring an option category and associating it with an option before
 parsing options (e.g. statically) will change the output of ``-help`` from
 uncategorized to categorized. If an option category is declared but not
-associated with an option then it will be hidden from the output of ``-help``
-but will be shown in the output of ``-help-hidden``.
+associated with an option then it will be hidden from the output of ``-help``.
 
 .. _different parser:
 .. _discussed previously:
diff --git a/llvm/lib/Support/CommandLine.cpp b/llvm/lib/Support/CommandLine.cpp
index 368dead4491492..7360d733d96e7b 100644
--- a/llvm/lib/Support/CommandLine.cpp
+++ b/llvm/lib/Support/CommandLine.cpp
@@ -2474,8 +2474,7 @@ class CategorizedHelpPrinter : public HelpPrinter {
     for (OptionCategory *Category : SortedCategories) {
       // Hide empty categories for --help, but show for --help-hidden.
       const auto &CategoryOptions = CategorizedOptions[Category];
-      bool IsEmptyCategory = CategoryOptions.empty();
-      if (!ShowHidden && IsEmptyCategory)
+      if (CategoryOptions.empty())
         continue;
 
       // Print category information.
@@ -2488,12 +2487,6 @@ class CategorizedHelpPrinter : public HelpPrinter {
       else
         outs() << "\n";
 
-      // When using --help-hidden explicitly state if the category has no
-      // options associated with it.
-      if (IsEmptyCategory) {
-        outs() << "  This option category has no options.\n";
-        continue;
-      }
       // Loop over the options in the category and print.
       for (const Option *Opt : CategoryOptions)
         Opt->printOptionInfo(MaxArgLen);
diff --git a/llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test b/llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test
index c9c2dbe9fa3ea6..15daec0ba59304 100644
--- a/llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test
+++ b/llvm/test/tools/llvm-debuginfo-analyzer/cmdline.test
@@ -70,8 +70,6 @@ HELP-ALL:     =system                  -   Display PDB's MS system elements.
 HELP-ALL:     =typename                -   Include Parameters in templates.
 HELP-ALL:     =underlying              -   Underlying type for type definitions.
 HELP-ALL:     =zero                    -   Zero line numbers.
-HELP-ALL: Color Options:
-HELP-ALL:   This option category has no options.
 HELP-ALL: Compare Options:
 HELP-ALL: These control the view comparison.
 HELP-ALL:   --compare=<value>          - Elements to compare.
@@ -81,8 +79,6 @@ HELP-ALL:     =scopes                  -   Scopes.
 HELP-ALL:     =symbols                 -   Symbols.
 HELP-ALL:     =types                   -   Types.
 HELP-ALL:   --compare-context          - Add the view as compare context.
-HELP-ALL: General options:
-HELP-ALL:   This option category has no options.
 HELP-ALL: Generic Options:
 HELP-ALL:   -h                         - Alias for --help
 HELP-ALL:   --help                     - Display available options (--help-hidden for more)
diff --git a/llvm/unittests/Support/CommandLineTest.cpp b/llvm/unittests/Support/CommandLineTest.cpp
index a9d0790c8fea22..99d99c74c128b0 100644
--- a/llvm/unittests/Support/CommandLineTest.cpp
+++ b/llvm/unittests/Support/CommandLineTest.cpp
@@ -2301,4 +2301,29 @@ TEST(CommandLineTest, SubCommandGroups) {
   EXPECT_FALSE(SC3.OptionsMap.contains("opt12"));
 }
 
+TEST(CommandLineTest, HelpWithEmptyCategory) {
+  cl::ResetCommandLineParser();
+
+  cl::OptionCategory Category1("First Category");
+  cl::OptionCategory Category2("Second Category");
+  StackOption<int> Opt1("opt1", cl::cat(Category1));
+  StackOption<int> Opt2("opt2", cl::cat(Category2));
+  cl::HideUnrelatedOptions(Category2);
+
+  const char *args[] = {"prog"};
+  EXPECT_TRUE(cl::ParseCommandLineOptions(std::size(args), args, StringRef(),
+                                          &llvm::nulls()));
+  auto Output = interceptStdout(
+      []() { cl::PrintHelpMessage(/*Hidden=*/false, /*Categorized=*/true); });
+  EXPECT_EQ(std::string::npos, Output.find("First Category"))
+      << "An empty category should not be printed";
+
+  Output = interceptStdout(
+      []() { cl::PrintHelpMessage(/*Hidden=*/true, /*Categorized=*/true); });
+  EXPECT_EQ(std::string::npos, Output.find("First Category"))
+      << "An empty category should not be printed";
+
+  cl::ResetCommandLineParser();
+}
+
 } // anonymous namespace

[jh7370]

LGTM. I can't imagine any reason to maintain the existing behaviour.

[dexonsmith]

LGTM too.

[CarlosAlbertoEnciso]

LGTM too.