BTS-874 | Documentation/immutable-startup-options (#16486)

Some options cannot be changed (easily) again, like extended database names

arangod/Aql/OptimizerRulesFeature.cpp

@@ -58,8 +58,9 @@ void OptimizerRulesFeature::collectOptions(
     std::shared_ptr<arangodb::options::ProgramOptions> options) {
   options
       ->addOption("--query.optimizer-rules",
-                  "enable or disable specific optimizer rules (use rule name "
-                  "prefixed with '-' for disabling, '+' for enabling)",
+                  "Enable or disable specific optimizer rules by default. "
+                  "Specify the rule name prefixed with `-` for disabling, or "
+                  "`+` for enabling.",
                   new arangodb::options::VectorParameter<
                       arangodb::options::StringParameter>(&_optimizerRules),
                   arangodb::options::makeDefaultFlags(

arangod/GeneralServer/GeneralServerFeature.cpp

@@ -251,8 +251,8 @@ void GeneralServerFeature::collectOptions(
 
   options
       ->addOption("--http.return-queue-time-header",
-                  "if true, return the 'x-arango-queue-time-seconds' header in "
-                  "responses",
+                  "If true, return the `x-arango-queue-time-seconds` header in "
+                  "responses.",
                   new BooleanParameter(&_returnQueueTimeHeader))
       .setIntroducedIn(30900);
 
@@ -277,8 +277,8 @@ void GeneralServerFeature::collectOptions(
                         "web-interface.trusted-proxy");
 
   options->addOption("--web-interface.trusted-proxy",
-                     "list of proxies to trust (may be IP or network). Make "
-                     "sure --web-interface.proxy-request-check is enabled",
+                     "List of proxies to trust (can be IP or network). Make "
+                     "sure `--web-interface.proxy-request-check` is enabled.",
                      new VectorParameter<StringParameter>(&_trustedProxies),
                      arangodb::options::makeFlags(
                          arangodb::options::Flags::DefaultNoComponents,

arangod/Pregel/PregelFeature.cpp

@@ -350,8 +350,8 @@ void PregelFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--pregel.memory-mapped-files-custom-path",
-                  "custom path for Pregel's temporary files (only used if "
-                  "`--pregel.memory-mapped-files-location` is 'custom')",
+                  "Custom path for Pregel's temporary files. Only used if "
+                  "`--pregel.memory-mapped-files-location` is \"custom\".",
                   new StringParameter(&_tempLocationCustomPath),
                   arangodb::options::makeFlags(
                       arangodb::options::Flags::DefaultNoComponents,

arangod/RestServer/DatabaseFeature.cpp

@@ -494,7 +494,8 @@ void DatabaseFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--database.extended-names-databases",
-                  "allow extended characters in database names",
+                  "Allow most UTF-8 characters in database names. Once in use, "
+                  "this option cannot be turned off again.",
                   new BooleanParameter(&_extendedNamesForDatabases),
                   arangodb::options::makeDefaultFlags(
                       arangodb::options::Flags::Uncommon,
@@ -512,7 +513,7 @@ void DatabaseFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
   // the following option was obsoleted in 3.9
   options->addObsoleteOption(
       "--database.old-system-collections",
-      "create and use deprecated system collection (_modules, _fishbowl)",
+      "Create and use deprecated system collection (_modules, _fishbowl).",
       false);
 
   // the following option was obsoleted in 3.8

arangod/RestServer/EndpointFeature.cpp

@@ -59,9 +59,9 @@ void EndpointFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
   options->addOldOption("server.reuse-address", "tcp.reuse-address");
 
   options->addOption("--server.endpoint",
-                     "endpoint for client requests (e.g. "
-                     "'http+tcp://127.0.0.1:8529', or "
-                     "'vst+ssl://192.168.1.1:8529')",
+                     "Endpoint for client requests (e.g. "
+                     "`http+tcp://127.0.0.1:8529`, or "
+                     "`vst+ssl://192.168.1.1:8529`)",
                      new VectorParameter<StringParameter>(&_endpoints));
 
   options->addSection("tcp", "TCP features");

arangod/RestServer/QueryRegistryFeature.cpp

@@ -316,7 +316,8 @@ void QueryRegistryFeature::collectOptions(
                      new DoubleParameter(&_slowStreamingQueryThreshold));
 
   options->addOption("--query.cache-mode",
-                     "mode for the AQL query result cache (on, off, demand)",
+                     "Mode for the AQL query result cache. Can be \"on\", "
+                     "\"off\", or \"demand\".",
                      new StringParameter(&_queryCacheMode));
 
   options->addOption(

arangod/RocksDBEngine/RocksDBOptionFeature.cpp

@@ -244,7 +244,7 @@ void RocksDBOptionFeature::collectOptions(
 
   options
       ->addOption("--rocksdb.target-file-size-base",
-                  "per-file target file size for compaction (in bytes). the "
+                  "Per-file target file size for compaction (in bytes). The "
                   "actual target file size for each level is "
                   "`--rocksdb.target-file-size-base` multiplied by "
                   "`--rocksdb.target-file-size-multiplier` ^ (level - 1)",
@@ -915,8 +915,8 @@ void RocksDBOptionFeature::collectOptions(
             family);
         options
             ->addOption("--rocksdb.max-write-buffer-number-" + name,
-                        "if non-zero, overrides the value of "
-                        "--rocksdb.max-write-buffer-number for the " +
+                        "If non-zero, overrides the value of "
+                        "`--rocksdb.max-write-buffer-number` for the " +
                             name + " column family",
                         new UInt64Parameter(&_maxWriteBufferNumberCf[index]),
                         arangodb::options::makeDefaultFlags(

client-tools/Benchmark/BenchFeature.cpp

@@ -183,8 +183,8 @@ void BenchFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--create-collection",
-                  "whether we should create the collection specified via "
-                  "the --collection parameter",
+                  "Whether we should create the collection specified via "
+                  "the `--collection` parameter",
                   new BooleanParameter(&_createCollection))
       .setIntroducedIn(31000);
 
@@ -226,7 +226,7 @@ void BenchFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--custom-query",
-                  "the query to be used in the 'custom-query' testcase",
+                  "The query to be used in the \"custom-query\" testcase.",
                   new StringParameter(&_customQuery))
       .setIntroducedIn(30800);
 
@@ -240,9 +240,10 @@ void BenchFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
       .setIntroducedIn(30800);
 
   options
-      ->addOption("--custom-query-bindvars",
-                  "bind parameters to be used in the 'custom-query' testcase.",
-                  new StringParameter(&_customQueryBindVars))
+      ->addOption(
+          "--custom-query-bindvars",
+          "The bind parameters to be used in the `custom-query` testcase.",
+          new StringParameter(&_customQueryBindVars))
       .setIntroducedIn(31000);
 
   options->addOption("--quiet", "suppress status messages",

client-tools/Export/ExportFeature.cpp

@@ -115,8 +115,8 @@ void ExportFeature::collectOptions(
 
   options
       ->addOption("--custom-query-bindvars",
-                  "bind parameters to be used with '--custom-query' or "
-                  "custom-query-file'",
+                  "The bind parameters to be used with the `--custom-query` or "
+                  "`--custom-query-file` option.",
                   new StringParameter(&_customQueryBindVars))
       .setIntroducedIn(31000);
 
@@ -127,7 +127,7 @@ void ExportFeature::collectOptions(
                      new BooleanParameter(&_xgmmlLabelOnly));
 
   options->addOption("--xgmml-label-attribute",
-                     "specify document attribute that will be the xgmml label",
+                     "Specify document attribute that will be the XGMML label.",
                      new StringParameter(&_xgmmlLabelAttribute));
 
   options->addOption("--output-directory", "output directory",

client-tools/Import/ImportFeature.cpp

@@ -83,7 +83,7 @@ ImportFeature::ImportFeature(Server& server, int* result)
 
 void ImportFeature::collectOptions(
     std::shared_ptr<options::ProgramOptions> options) {
-  options->addOption("--file", "file name (\"-\" for STDIN)",
+  options->addOption("--file", "File name (\"-\" for stdin).",
                      new StringParameter(&_filename));
 
   options
@@ -95,7 +95,7 @@ void ImportFeature::collectOptions(
 
   options->addOption(
       "--backslash-escape",
-      "use backslash as the escape character for quotes, used for csv",
+      "Use backslash as the escape character for quotes, used for CSV.",
       new BooleanParameter(&_useBackslash));
 
   options->addOption("--batch-size",
@@ -111,8 +111,8 @@ void ImportFeature::collectOptions(
                      new StringParameter(&_collectionName));
 
   options->addOption("--from-collection-prefix",
-                     "_from collection name prefix (will be prepended to all "
-                     "values in '_from')",
+                     "The collection name prefix that will be prepended to all "
+                     "values in `_from`.",
                      new StringParameter(&_fromCollectionPrefix));
 
   options->addOption(
@@ -141,26 +141,28 @@ void ImportFeature::collectOptions(
       .setIntroducedIn(30800);
 
   options->addOption("--skip-lines",
-                     "number of lines to skip for formats (csv and tsv only)",
+                     "Number of lines to skip for formats (CSV and TSV only).",
                      new UInt64Parameter(&_rowsToSkip));
 
-  options->addOption("--convert",
-                     "convert the strings 'null', 'false', 'true' and strings "
-                     "containing numbers into non-string types (csv and tsv "
-                     "only)",
-                     new BooleanParameter(&_convert));
+  options->addOption(
+      "--convert",
+      "Convert the strings `null`, `false`, `true` and strings "
+      "containing numbers into non-string types. For CSV and TSV "
+      "only.",
+      new BooleanParameter(&_convert));
 
   options->addOption("--translate",
-                     "translate an attribute name (use as --translate "
-                     "\"from=to\", for csv and tsv only)",
+                     "Translate an attribute name using the syntax "
+                     "`\"from=to\"`. For CSV and TSV only. ",
                      new VectorParameter<StringParameter>(&_translations));
 
   options
-      ->addOption("--datatype",
-                  "force a specific datatype for an attribute "
-                  "(null/boolean/number/string). Use as \"attribute=type\". "
-                  "For CSV and TSV only. Takes precendence over --convert",
-                  new VectorParameter<StringParameter>(&_datatypes))
+      ->addOption(
+          "--datatype",
+          "Force a specific datatype for an attribute "
+          "(null/boolean/number/string) using the syntax `\"attribute=type\"`. "
+          "For CSV and TSV only. Takes precedence over `--convert`.",
+          new VectorParameter<StringParameter>(&_datatypes))
       .setIntroducedIn(30900);
 
   options->addOption("--remove-attribute",
@@ -191,7 +193,7 @@ void ImportFeature::collectOptions(
       "from the collection)",
       new BooleanParameter(&_overwrite));
 
-  options->addOption("--quote", "quote character(s), used for csv",
+  options->addOption("--quote", "Quote character(s), used for CSV.",
                      new StringParameter(&_quote));
 
   options->addOption(
@@ -204,7 +206,7 @@ void ImportFeature::collectOptions(
   options->addOption("--progress", "show progress",
                      new BooleanParameter(&_progress));
 
-  options->addOption("--ignore-missing", "ignore missing columns in csv input",
+  options->addOption("--ignore-missing", "Ignore missing columns in CSV input.",
                      new BooleanParameter(&_ignoreMissing));
 
   std::unordered_set<std::string> actions = {"error", "update", "replace",

client-tools/Restore/RestoreFeature.cpp

@@ -1753,9 +1753,9 @@ void RestoreFeature::collectOptions(
 
   options
       ->addOption("--enable-revision-trees",
-                  "enable revision trees for new collections if the collection "
-                  "attributes 'syncByRevision' and "
-                  "'usesRevisionsAsDocumentIds' are missing",
+                  "Enable revision trees for new collections if the collection "
+                  "attributes `syncByRevision` and "
+                  "`usesRevisionsAsDocumentIds` are missing.",
                   new BooleanParameter(&_options.enableRevisionTrees))
       .setIntroducedIn(30807);
 

client-tools/Shell/V8ShellFeature.cpp

@@ -127,7 +127,7 @@ void V8ShellFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
                      new BooleanParameter(&_currentModuleDirectory));
 
   options->addOption("--javascript.copy-installation",
-                     "copy contents of 'javascript.startup-directory'",
+                     "Copy contents of `--javascript.startup-directory`.",
                      new BooleanParameter(&_copyInstallation));
 
   options->addOption(

lib/ApplicationFeatures/ConfigFeature.cpp

@@ -48,18 +48,21 @@ using namespace arangodb::options;
 namespace arangodb {
 
 void ConfigFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
-  options->addOption("--configuration,-c", "the configuration file or 'none'",
+  options->addOption("--configuration,-c",
+                     "The configuration file or \"none\".",
                      new StringParameter(&_file));
 
   // add --config as an alias for --configuration. both point to the same
   // variable!
   options->addOption(
-      "--config", "the configuration file or 'none'",
+      "--config", "The configuration file or \"none\".",
       new StringParameter(&_file),
       arangodb::options::makeDefaultFlags(arangodb::options::Flags::Uncommon));
 
   options->addOption(
-      "--define,-D", "define key=value for a @key@ entry in config file",
+      "--define,-D",
+      "Define a value for a `@key@` entry in the configuration file using the "
+      "syntax `\"key=value\"`.",
       new VectorParameter<StringParameter>(&_defines),
       arangodb::options::makeDefaultFlags(arangodb::options::Flags::Uncommon));
 

lib/ApplicationFeatures/LanguageFeature.cpp

@@ -104,25 +104,33 @@ LanguageFeature::~LanguageFeature() = default;
 void LanguageFeature::collectOptions(
     std::shared_ptr<options::ProgramOptions> options) {
   options
-      ->addOption("--default-language", "ISO-639 language code",
+      ->addOption("--default-language",
+                  "An ISO-639 language code. This option can only be set once, "
+                  "when initializing the database.",
                   new StringParameter(&_defaultLanguage),
                   arangodb::options::makeDefaultFlags(
                       arangodb::options::Flags::Uncommon))
       .setDeprecatedIn(31000);
 
   options
-      ->addOption("--icu-language", "ICU language",
-                  new StringParameter(&_icuLanguage),
-                  arangodb::options::makeDefaultFlags(
-                      arangodb::options::Flags::Uncommon))
+      ->addOption(
+          "--icu-language",
+          "An ICU locale ID to set a language and optionally additional "
+          "properties that affect string comparisons and sorting. This option "
+          "can only be set once, when initializing the database.",
+          new StringParameter(&_icuLanguage),
+          arangodb::options::makeDefaultFlags(
+              arangodb::options::Flags::Uncommon))
       .setIntroducedIn(30901);
 
   options
-      ->addOption("--default-language-check",
-                  "check if default language matches stored language",
-                  new BooleanParameter(&_forceLanguageCheck),
-                  arangodb::options::makeDefaultFlags(
-                      arangodb::options::Flags::Uncommon))
+      ->addOption(
+          "--default-language-check",
+          "Check if `--icu-language` / `--default-language` matches the "
+          "stored language.",
+          new BooleanParameter(&_forceLanguageCheck),
+          arangodb::options::makeDefaultFlags(
+              arangodb::options::Flags::Uncommon))
       .setIntroducedIn(30800);
 }
 

lib/Logger/LoggerFeature.cpp

@@ -226,8 +226,9 @@ void LoggerFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--log.hostname",
-                  "hostname to use in log message (empty for none, use 'auto' "
-                  "to automatically figure out hostname)",
+                  "The hostname to use in log message. Leave empty for none, "
+                  "use \"auto\" "
+                  "to automatically determine a hostname.",
                   new StringParameter(&_hostname))
       .setIntroducedIn(30800);
 
@@ -251,7 +252,7 @@ void LoggerFeature::collectOptions(std::shared_ptr<ProgramOptions> options) {
 
   options
       ->addOption("--log.performance",
-                  "shortcut for '--log.level performance=trace'",
+                  "Shortcut for `--log.level performance=trace`.",
                   new BooleanParameter(&_performance),
                   arangodb::options::makeDefaultFlags(
                       arangodb::options::Flags::Uncommon))