cmDocumentation: `char*[][2]` → `cmDocumentationEntry[N]`

Use fixed size arrays of `cmDocumentationEntry` items instead of
open arrays of two `char` pointers when describe program options
help screens.

Also, drop `const char*[][2]` overloads of methods of
`cmDocumentation` and `cmDocumentationSection` classes in the sake
of generic (template) appenders introduced earlier.

Source/CMakeLists.txt

@@ -196,7 +196,6 @@ add_library(
   cmDependsCompiler.h
   cmDocumentation.cxx
   cmDocumentationFormatter.cxx
-  cmDocumentationSection.cxx
   cmDynamicLoader.cxx
   cmDynamicLoader.h
   cmELF.h

Source/CPack/cpack.cxx

@@ -25,7 +25,6 @@
 #include "cmConsoleBuf.h"
 #include "cmDocumentation.h"
 #include "cmDocumentationEntry.h"
-#include "cmDocumentationFormatter.h"
 #include "cmGlobalGenerator.h"
 #include "cmMakefile.h"
 #include "cmState.h"
@@ -36,19 +35,14 @@
 #include "cmake.h"
 
 namespace {
-const char* cmDocumentationName[][2] = {
-  { nullptr, "  cpack - Packaging driver provided by CMake." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationName = {
+  nullptr, "  cpack - Packaging driver provided by CMake."
 };
 
-const char* cmDocumentationUsage[][2] = {
-  // clang-format off
-  { nullptr, "  cpack [options]" },
-  { nullptr, nullptr }
-  // clang-format on
-};
+const cmDocumentationEntry cmDocumentationUsage = { nullptr,
+                                                    "  cpack [options]" };
 
-const char* cmDocumentationOptions[][2] = {
+const cmDocumentationEntry cmDocumentationOptions[14] = {
   { "-G <generators>", "Override/define CPACK_GENERATOR" },
   { "-C <Configuration>", "Specify the project configuration" },
   { "-D <var>=<value>", "Set a CPack variable." },
@@ -62,8 +56,7 @@ const char* cmDocumentationOptions[][2] = {
   { "-B <packageDirectory>", "Override/define CPACK_PACKAGE_DIRECTORY" },
   { "--vendor <vendorName>", "Override/define CPACK_PACKAGE_VENDOR" },
   { "--preset", "Read arguments from a package preset" },
-  { "--list-presets", "List available package presets" },
-  { nullptr, nullptr }
+  { "--list-presets", "List available package presets" }
 };
 
 void cpackProgressCallback(const std::string& message, float /*unused*/)

Source/CursesDialog/ccmake.cxx

@@ -16,7 +16,7 @@
 #include "cmCursesMainForm.h"
 #include "cmCursesStandardIncludes.h"
 #include "cmDocumentation.h"
-#include "cmDocumentationEntry.h" // IWYU pragma: keep
+#include "cmDocumentationEntry.h"
 #include "cmMessageMetadata.h"
 #include "cmState.h"
 #include "cmStringAlgorithms.h"
@@ -24,12 +24,11 @@
 #include "cmake.h"
 
 namespace {
-const char* cmDocumentationName[][2] = {
-  { nullptr, "  ccmake - Curses Interface for CMake." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationName = {
+  nullptr, "  ccmake - Curses Interface for CMake."
 };
 
-const char* cmDocumentationUsage[][2] = {
+const cmDocumentationEntry cmDocumentationUsage[2] = {
   { nullptr,
     "  ccmake <path-to-source>\n"
     "  ccmake <path-to-existing-build>" },
@@ -37,17 +36,12 @@ const char* cmDocumentationUsage[][2] = {
     "Specify a source directory to (re-)generate a build system for "
     "it in the current working directory.  Specify an existing build "
     "directory to re-generate its build system." },
-  { nullptr, nullptr }
 };
 
-const char* cmDocumentationUsageNote[][2] = {
-  { nullptr, "Run 'ccmake --help' for more information." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationUsageNote = {
+  nullptr, "Run 'ccmake --help' for more information."
 };
 
-const char* cmDocumentationOptions[][2] = { CMAKE_STANDARD_OPTIONS_TABLE,
-                                            { nullptr, nullptr } };
-
 #ifndef _WIN32
 extern "C" {
 
@@ -89,8 +83,8 @@ int main(int argc, char const* const* argv)
       doc.AppendSection("Usage", cmDocumentationUsageNote);
     }
     doc.AppendSection("Generators", generators);
-    doc.PrependSection("Options", cmDocumentationOptions);
-    return doc.PrintRequestedDocumentation(std::cout) ? 0 : 1;
+    doc.PrependSection("Options", cmake::CMAKE_STANDARD_OPTIONS_TABLE);
+    return !doc.PrintRequestedDocumentation(std::cout);
   }
 
   bool debug = false;

Source/QtDialog/CMakeSetup.cxx

@@ -23,25 +23,23 @@
 #include "cmake.h"
 
 namespace {
-const char* cmDocumentationName[][2] = { { nullptr,
-                                           "  cmake-gui - CMake GUI." },
-                                         { nullptr, nullptr } };
-
-const char* cmDocumentationUsage[][2] = {
-  { nullptr,
-    "  cmake-gui [options]\n"
-    "  cmake-gui [options] <path-to-source>\n"
-    "  cmake-gui [options] <path-to-existing-build>\n"
-    "  cmake-gui [options] -S <path-to-source> -B <path-to-build>\n"
-    "  cmake-gui [options] --browse-manual\n" },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationName = {
+  nullptr, "  cmake-gui - CMake GUI."
 };
 
-const char* cmDocumentationOptions[][2] = {
+const cmDocumentationEntry cmDocumentationUsage = {
+  nullptr,
+  "  cmake-gui [options]\n"
+  "  cmake-gui [options] <path-to-source>\n"
+  "  cmake-gui [options] <path-to-existing-build>\n"
+  "  cmake-gui [options] -S <path-to-source> -B <path-to-build>\n"
+  "  cmake-gui [options] --browse-manual"
+};
+
+const cmDocumentationEntry cmDocumentationOptions[3] = {
   { "-S <path-to-source>", "Explicitly specify a source directory." },
   { "-B <path-to-build>", "Explicitly specify a build directory." },
-  { "--preset=<preset>", "Specify a configure preset." },
-  { nullptr, nullptr }
+  { "--preset=<preset>", "Specify a configure preset." }
 };
 } // anonymous namespace
 

Source/cmDocumentation.cxx

@@ -17,7 +17,7 @@
 #include "cmVersion.h"
 
 namespace {
-const char* cmDocumentationStandardOptions[][2] = {
+const cmDocumentationEntry cmDocumentationStandardOptions[20] = {
   { "-h,-H,--help,-help,-usage,/?", "Print usage information and exit." },
   { "--version,-version,/V [<file>]", "Print version number and exit." },
   { "--help-full [<file>]", "Print all help manuals and exit." },
@@ -43,20 +43,17 @@ const char* cmDocumentationStandardOptions[][2] = {
   { "--help-variable var [<file>]", "Print help for one variable and exit." },
   { "--help-variable-list [<file>]",
     "List variables with help available and exit." },
-  { "--help-variables [<file>]", "Print cmake-variables manual and exit." },
-  { nullptr, nullptr }
+  { "--help-variables [<file>]", "Print cmake-variables manual and exit." }
 };
 
-const char* cmDocumentationCPackGeneratorsHeader[][2] = {
-  { nullptr, "The following generators are available on this platform:" },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationCPackGeneratorsHeader = {
+  nullptr, "The following generators are available on this platform:"
 };
 
-const char* cmDocumentationCMakeGeneratorsHeader[][2] = {
-  { nullptr,
-    "The following generators are available on this platform (* marks "
-    "default):" },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationCMakeGeneratorsHeader = {
+  nullptr,
+  "The following generators are available on this platform (* marks "
+  "default):"
 };
 
 bool isOption(const char* arg)
@@ -373,13 +370,6 @@ void cmDocumentation::SetSection(const char* name,
   this->SectionAtName(name) = std::move(section);
 }
 
-void cmDocumentation::SetSection(const char* name, const char* docs[][2])
-{
-  cmDocumentationSection sec{ name };
-  sec.Append(docs);
-  this->SetSection(name, std::move(sec));
-}
-
 void cmDocumentation::SetSections(
   std::map<std::string, cmDocumentationSection> sections)
 {
@@ -393,16 +383,6 @@ cmDocumentationSection& cmDocumentation::SectionAtName(const char* name)
     .first->second;
 }
 
-void cmDocumentation::PrependSection(const char* name, const char* docs[][2])
-{
-  this->SectionAtName(name).Prepend(docs);
-}
-
-void cmDocumentation::AppendSection(const char* name, const char* docs[][2])
-{
-  this->SectionAtName(name).Append(docs);
-}
-
 void cmDocumentation::AppendSection(const char* name,
                                     cmDocumentationEntry& docs)
 {

Source/cmDocumentation.h

@@ -82,18 +82,15 @@ public:
     sec.Append(docs);
     this->SetSection(sectionName, std::move(sec));
   }
-  void SetSection(const char* sectionName, const char* docs[][2]);
   void SetSections(std::map<std::string, cmDocumentationSection> sections);
 
   /** Add the documentation to the beginning/end of the section */
-  void PrependSection(const char* sectionName, const char* docs[][2]);
   template <typename Iterable>
   void PrependSection(const char* sectionName, const Iterable& docs)
   {
     this->SectionAtName(sectionName).Prepend(docs);
   }
   void PrependSection(const char* sectionName, cmDocumentationEntry& docs);
-  void AppendSection(const char* sectionName, const char* docs[][2]);
   template <typename Iterable>
   void AppendSection(const char* sectionName, const Iterable& docs)
   {

Source/cmDocumentationEntry.h

@@ -13,7 +13,7 @@ struct cmDocumentationEntry
   std::string Brief;
   char CustomNamePrefix = ' ';
   cmDocumentationEntry() = default;
-  cmDocumentationEntry(const char* n, const char* b)
+  cmDocumentationEntry(const char* const n, const char* const b)
   {
     if (n) {
       this->Name = n;

Source/cmDocumentationSection.cxx

@@ -1,28 +0,0 @@
-/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-   file Copyright.txt or https://cmake.org/licensing for details.  */
-#include "cmDocumentationSection.h"
-
-void cmDocumentationSection::Append(const char* data[][2])
-{
-  int i = 0;
-  while (data[i][1]) {
-    this->Entries.emplace_back(data[i][0], data[i][1]);
-    data += 1;
-  }
-}
-
-void cmDocumentationSection::Prepend(const char* data[][2])
-{
-  std::vector<cmDocumentationEntry> tmp;
-  int i = 0;
-  while (data[i][1]) {
-    tmp.emplace_back(data[i][0], data[i][1]);
-    data += 1;
-  }
-  this->Entries.insert(this->Entries.begin(), tmp.begin(), tmp.end());
-}
-
-void cmDocumentationSection::Append(const char* n, const char* b)
-{
-  this->Entries.emplace_back(n, b);
-}

Source/cmDocumentationSection.h

@@ -53,12 +53,12 @@ public:
   }
 
   /** Append an entry to this section using NULL terminated chars */
-  void Append(const char* [][2]);
-  void Append(const char* n, const char* b);
+  void Append(const char* n, const char* b)
+  {
+    this->Entries.emplace_back(n, b);
+  }
 
   /** prepend some documentation to this section */
-  void Prepend(const char* [][2]);
-
   template <typename Iterable>
   void Prepend(const Iterable& entries)
   {

Source/cmake.cxx

@@ -40,7 +40,6 @@
 #include "cmCommands.h"
 #include "cmDocumentation.h"
 #include "cmDocumentationEntry.h"
-#include "cmDocumentationFormatter.h"
 #include "cmDuration.h"
 #include "cmExternalMakefileProjectGenerator.h"
 #include "cmFileTimeCache.h"
@@ -165,6 +164,32 @@ static void cmWarnUnusedCliWarning(const std::string& variable, int /*unused*/,
 }
 #endif
 
+cmDocumentationEntry cmake::CMAKE_STANDARD_OPTIONS_TABLE[18] = {
+  { "-S <path-to-source>", "Explicitly specify a source directory." },
+  { "-B <path-to-build>", "Explicitly specify a build directory." },
+  { "-C <initial-cache>", "Pre-load a script to populate the cache." },
+  { "-D <var>[:<type>]=<value>", "Create or update a cmake cache entry." },
+  { "-U <globbing_expr>", "Remove matching entries from CMake cache." },
+  { "-G <generator-name>", "Specify a build system generator." },
+  { "-T <toolset-name>", "Specify toolset name if supported by generator." },
+  { "-A <platform-name>", "Specify platform name if supported by generator." },
+  { "--toolchain <file>", "Specify toolchain file [CMAKE_TOOLCHAIN_FILE]." },
+  { "--install-prefix <directory>",
+    "Specify install directory [CMAKE_INSTALL_PREFIX]." },
+  { "-Wdev", "Enable developer warnings." },
+  { "-Wno-dev", "Suppress developer warnings." },
+  { "-Werror=dev", "Make developer warnings errors." },
+  { "-Wno-error=dev", "Make developer warnings not errors." },
+  { "-Wdeprecated", "Enable deprecation warnings." },
+  { "-Wno-deprecated", "Suppress deprecation warnings." },
+  { "-Werror=deprecated",
+    "Make deprecated macro and function warnings "
+    "errors." },
+  { "-Wno-error=deprecated",
+    "Make deprecated macro and function warnings "
+    "not errors." }
+};
+
 cmake::cmake(Role role, cmState::Mode mode, cmState::ProjectKind projectKind)
   : CMakeWorkingDirectory(cmSystemTools::GetCurrentWorkingDirectory())
   , FileTimeCache(cm::make_unique<cmFileTimeCache>())

Source/cmake.h

@@ -18,6 +18,7 @@
 #include <cm/string_view>
 #include <cmext/string_view>
 
+#include "cmDocumentationEntry.h"
 #include "cmGeneratedFileStream.h"
 #include "cmInstalledFile.h"
 #include "cmListFileCache.h"
@@ -45,7 +46,6 @@ class cmMakefile;
 class cmMessenger;
 class cmVariableWatch;
 struct cmBuildOptions;
-struct cmDocumentationEntry;
 
 /** \brief Represents a cmake invocation.
  *
@@ -793,37 +793,10 @@ private:
 #if !defined(CMAKE_BOOTSTRAP)
   std::unique_ptr<cmMakefileProfilingData> ProfilingOutput;
 #endif
-};
 
-#define CMAKE_STANDARD_OPTIONS_TABLE                                          \
-  { "-S <path-to-source>", "Explicitly specify a source directory." },        \
-    { "-B <path-to-build>", "Explicitly specify a build directory." },        \
-    { "-C <initial-cache>", "Pre-load a script to populate the cache." },     \
-    { "-D <var>[:<type>]=<value>", "Create or update a cmake cache entry." }, \
-    { "-U <globbing_expr>", "Remove matching entries from CMake cache." },    \
-    { "-G <generator-name>", "Specify a build system generator." },           \
-    { "-T <toolset-name>",                                                    \
-      "Specify toolset name if supported by generator." },                    \
-    { "-A <platform-name>",                                                   \
-      "Specify platform name if supported by generator." },                   \
-    { "--toolchain <file>",                                                   \
-      "Specify toolchain file [CMAKE_TOOLCHAIN_FILE]." },                     \
-    { "--install-prefix <directory>",                                         \
-      "Specify install directory [CMAKE_INSTALL_PREFIX]." },                  \
-    { "-Wdev", "Enable developer warnings." },                                \
-    { "-Wno-dev", "Suppress developer warnings." },                           \
-    { "-Werror=dev", "Make developer warnings errors." },                     \
-    { "-Wno-error=dev", "Make developer warnings not errors." },              \
-    { "-Wdeprecated", "Enable deprecation warnings." },                       \
-    { "-Wno-deprecated", "Suppress deprecation warnings." },                  \
-    { "-Werror=deprecated",                                                   \
-      "Make deprecated macro and function warnings "                          \
-      "errors." },                                                            \
-  {                                                                           \
-    "-Wno-error=deprecated",                                                  \
-      "Make deprecated macro and function warnings "                          \
-      "not errors."                                                           \
-  }
+public:
+  static cmDocumentationEntry CMAKE_STANDARD_OPTIONS_TABLE[18];
+};
 
 #define FOR_EACH_C90_FEATURE(F) F(c_function_prototypes)
 

Source/cmakemain.cxx

@@ -24,7 +24,7 @@
 #include "cmBuildOptions.h"
 #include "cmCommandLineArgument.h"
 #include "cmConsoleBuf.h"
-#include "cmDocumentationEntry.h" // IWYU pragma: keep
+#include "cmDocumentationEntry.h"
 #include "cmGlobalGenerator.h"
 #include "cmMakefile.h"
 #include "cmMessageMetadata.h"
@@ -46,12 +46,11 @@
 
 namespace {
 #ifndef CMAKE_BOOTSTRAP
-const char* cmDocumentationName[][2] = {
-  { nullptr, "  cmake - Cross-Platform Makefile Generator." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationName = {
+  nullptr, "  cmake - Cross-Platform Makefile Generator."
 };
 
-const char* cmDocumentationUsage[][2] = {
+const cmDocumentationEntry cmDocumentationUsage[2] = {
   { nullptr,
     "  cmake [options] <path-to-source>\n"
     "  cmake [options] <path-to-existing-build>\n"
@@ -59,17 +58,14 @@ const char* cmDocumentationUsage[][2] = {
   { nullptr,
     "Specify a source directory to (re-)generate a build system for "
     "it in the current working directory.  Specify an existing build "
-    "directory to re-generate its build system." },
-  { nullptr, nullptr }
+    "directory to re-generate its build system." }
 };
 
-const char* cmDocumentationUsageNote[][2] = {
-  { nullptr, "Run 'cmake --help' for more information." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationUsageNote = {
+  nullptr, "Run 'cmake --help' for more information."
 };
 
-const char* cmDocumentationOptions[][2] = {
-  CMAKE_STANDARD_OPTIONS_TABLE,
+const cmDocumentationEntry cmDocumentationOptions[31] = {
   { "--preset <preset>,--preset=<preset>", "Specify a configure preset." },
   { "--list-presets[=<type>]", "List available presets." },
   { "-E", "CMake command mode." },
@@ -118,8 +114,7 @@ const char* cmDocumentationOptions[][2] = {
     "google-trace" },
   { "--profiling-output=<file>",
     "Select an output path for the profiling data enabled through "
-    "--profiling-format." },
-  { nullptr, nullptr }
+    "--profiling-format." }
 };
 
 #endif
@@ -226,6 +221,7 @@ int do_cmake(int ac, char const* const* av)
     }
     doc.AppendSection("Generators", generators);
     doc.PrependSection("Options", cmDocumentationOptions);
+    doc.PrependSection("Options", cmake::CMAKE_STANDARD_OPTIONS_TABLE);
 
     return !doc.PrintRequestedDocumentation(std::cout);
   }

Source/ctest.cxx

@@ -11,21 +11,21 @@
 #include "cmCTest.h"
 #include "cmConsoleBuf.h"
 #include "cmDocumentation.h"
+#include "cmDocumentationEntry.h"
 #include "cmSystemTools.h"
 
 #include "CTest/cmCTestLaunch.h"
 #include "CTest/cmCTestScriptHandler.h"
 
 namespace {
-const char* cmDocumentationName[][2] = {
-  { nullptr, "  ctest - Testing driver provided by CMake." },
-  { nullptr, nullptr }
+const cmDocumentationEntry cmDocumentationName = {
+  nullptr, "  ctest - Testing driver provided by CMake."
 };
 
-const char* cmDocumentationUsage[][2] = { { nullptr, "  ctest [options]" },
-                                          { nullptr, nullptr } };
+const cmDocumentationEntry cmDocumentationUsage = { nullptr,
+                                                    "  ctest [options]" };
 
-const char* cmDocumentationOptions[][2] = {
+const cmDocumentationEntry cmDocumentationOptions[74] = {
   { "--preset <preset>, --preset=<preset>",
     "Read arguments from a test preset." },
   { "--list-presets", "List available test presets." },
@@ -155,8 +155,7 @@ const char* cmDocumentationOptions[][2] = {
   { "--no-compress-output", "Do not compress test output when submitting." },
   { "--print-labels", "Print all available test labels." },
   { "--no-tests=<[error|ignore]>",
-    "Regard no tests found either as 'error' or 'ignore' it." },
-  { nullptr, nullptr }
+    "Regard no tests found either as 'error' or 'ignore' it." }
 };
 } // anonymous namespace