docs: Better command help messages #118

bin/kong

@@ -18,7 +18,7 @@ local help_message = string.format([[
 Usage: kong <command>
 
 where <command> is one of:
-  start, stop, quit, restart, reload, config, db, version
+  start, restart, reload, stop, quit, db, version
 
 kong --help            print this message
 kong <command> --help  print the help message of a command

src/cli/config.lua

@@ -4,12 +4,14 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local IO = require "kong.tools.io"
 local args = require("lapp")(string.format([[
+For development purposes only.
+
 Duplicate an existing configuration for given environment.
 
 Usage: kong config [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
   -o,--output (default .)                  ouput
   -e,--env    (string)                     environment name
 ]], constants.CLI.GLOBAL_KONG_CONF))

src/cli/db.lua

@@ -8,7 +8,7 @@ local cutils = require "kong.cli.utils"
 local IO = require "kong.tools.io"
 local lapp = require("lapp")
 local args = lapp(string.format([[
-Migrations, seeding of the DB.
+Kong datastore management operations.
 
 Usage: kong db <command> [options]
 
@@ -17,9 +17,9 @@ Commands:
                        migrations, migrations:up, migrations:down, migrations:reset, seed, drop
 
 Options:
-  -c,--config (default %s) configuration file
-  -r,--random                              <seed>: flag to also insert random entities
-  -n,--number (default 1000)               <seed>: number of random entities to insert if --random
+  -c,--config (default %s) path to configuration file
+  -r,--random                              (seed) flag to also insert random entities
+  -n,--number (default 1000)               (seed) number of random entities to insert if --random
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 -- $ kong db

src/cli/quit.lua

@@ -4,12 +4,12 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
-Graceful shutdown
+Graceful shutdown. Stop the Kong instance running in the configured 'nginx_working_dir' directory.
 
 Usage: kong stop [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 -- Check if running, will exit if not

src/cli/reload.lua

@@ -4,12 +4,14 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
-Gracefully reload Kong applying any configuration changes (including nginx)
+Gracefully reload the Kong instance running in the configured 'nginx_working_dir'.
+
+Any configuration change will be applied.
 
 Usage: kong reload [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 signal.prepare_kong(args.config)

src/cli/restart.lua

@@ -4,10 +4,15 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
+Restart the Kong instance running in the configured 'nginx_working_dir'.
+
+Kong will be shutdown before restarting. For a zero-downtime reload
+of your configuration, look at 'kong reload'.
+
 Usage: kong restart [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 if signal.is_running(args.config) then

src/cli/start.lua

@@ -4,10 +4,12 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
+Start Kong with given configuration. Kong will run in the configured 'nginx_working_dir' directory.
+
 Usage: kong start [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 signal.prepare_kong(args.config)

src/cli/stop.lua

@@ -4,12 +4,12 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
-Fast shutdown
+Fast shutdown. Stop the Kong instance running in the configured 'nginx_working_dir' directory.
 
 Usage: kong stop [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 -- Check if running, will exit if not

src/cli/utils/utils.lua

@@ -103,7 +103,7 @@ local function get_kong_config_path(args_config)
   -- Make sure the configuration file really exists
   if not IO.file_exists(args_config) then
     logger:warn("No config at: "..args_config)
-    logger:error_exit("Could not find a configuration file.")
+    logger:error_exit("Could not find a path to configuration file.")
   end
 
   logger:log("Using config: "..args_config)