Merge pull request #1463 from kyanagi/refine-help-message

Refine `--help` messages

Author: soutaro

lib/steep/cli.rb

@@ -24,12 +24,13 @@ def process_global_options
         opts.banner = <<~USAGE
           Usage: steep [options]
 
-          available commands: #{CLI.available_commands.join(', ')}
+          Available commands:
+              #{CLI.available_commands.join(', ')}
 
           Options:
         USAGE
 
-        opts.on("--version") do
+        opts.on("--version", "Print Steep version") do
           process_version
           exit 0
         end
@@ -60,6 +61,10 @@ def run
       __send__(:"process_#{command}")
     end
 
+    def handle_steepfile_option(opts, command)
+      opts.on("--steepfile=PATH", "Specify path to Steepfile") {|path| command.steepfile = Pathname(path) }
+    end
+
     def handle_logging_options(opts)
       opts.on("--log-level=LEVEL", "Specify log level: debug, info, warn, error, fatal") do |level|
         Steep.logger.level = level
@@ -101,10 +106,16 @@ def setup_jobs_for_ci(jobs_option)
     def process_init
       Drivers::Init.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep init [options]"
+          opts.banner = <<BANNER
+Usage: steep init [options]
+
+Description:
+    Generates a Steepfile at specified path.
 
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
-          opts.on("--force") { command.force_write = true }
+Options:
+BANNER
+          handle_steepfile_option(opts, command)
+          opts.on("--force", "Overwrite the Steepfile if it already exists") { command.force_write = true }
 
           handle_logging_options opts
         end.parse!(argv)
@@ -114,9 +125,19 @@ def process_init
     def process_check
       Drivers::Check.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep check [options] [sources]"
+          opts.banner = <<BANNER
+Usage: steep check [options] [paths]
+
+Description:
+    Type check the program.
+
+    If paths are specified, it type checks and validates the files at the given path.
+    Otherwise, it type checks and validates all files in the project or the groups if specified.
+
+Options:
+BANNER
 
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+          handle_steepfile_option(opts, command)
           opts.on("--with-expectations[=PATH]", "Type check with expectations saved in PATH (or steep_expectations.yml)") do |path|
             command.with_expectations_path = Pathname(path || "steep_expectations.yml")
           end
@@ -179,9 +200,16 @@ def process_check
     def process_checkfile
       Drivers::Checkfile.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep checkfile [options] [files]"
+          opts.banner = <<BANNER
+Usage: steep checkfile [options] [files]
 
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+Description:
+    Deprecated: Use `steep check` instead.
+
+Options:
+BANNER
+
+          handle_steepfile_option(opts, command)
           opts.on("--all-rbs", "Type check all RBS files") { command.all_rbs = true }
           opts.on("--all-ruby", "Type check all Ruby files") { command.all_ruby = true }
           opts.on("--stdin", "Read files to type check from stdin") do
@@ -204,9 +232,16 @@ def process_checkfile
     def process_stats
       Drivers::Stats.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep stats [options] [sources]"
+          opts.banner = <<BANNER
+Usage: steep stats [options] [sources]
+
+Description:
+    Displays statistics about the typing of method calls.
 
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+Options:
+BANNER
+
+          handle_steepfile_option(opts, command)
           opts.on("--format=FORMAT", "Specify output format: csv, table") {|format| command.format = format }
           handle_jobs_option command.jobs_option, opts
           handle_logging_options opts
@@ -226,7 +261,14 @@ def process_validate
     def process_annotations
       Drivers::Annotations.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep annotations [options] [sources]"
+          opts.banner = <<BANNER
+Usage: steep annotations [options] [sources]
+
+Description:
+    Prints the type annotations in the Ruby code.
+
+Options:
+BANNER
           handle_logging_options opts
         end.parse!(argv)
 
@@ -237,8 +279,15 @@ def process_annotations
     def process_project
       Drivers::PrintProject.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep project [options]"
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+          opts.banner = <<BANNER
+Usage: steep project [options]
+
+Description:
+    Prints the project configuration.
+
+Options:
+BANNER
+          handle_steepfile_option(opts, command)
           opts.on("--[no-]print-files", "Print files") {|v|
             command.print_files = v ? true : false
           }
@@ -250,7 +299,15 @@ def process_project
     def process_watch
       Drivers::Watch.new(stdout: stdout, stderr: stderr).tap do |command|
         OptionParser.new do |opts|
-          opts.banner = "Usage: steep watch [options] [dirs]"
+          opts.banner = <<BANNER
+Usage: steep watch [options] [dirs]
+
+Description:
+    Monitors file changes and automatically type checks updated files.
+    Using LSP is recommended for better performance and more features.
+
+Options:
+BANNER
           opts.on("--severity-level=LEVEL", /^error|warning|information|hint$/, "Specify the minimum diagnostic severity to be recognized as an error (defaults: warning): error, warning, information, or hint") do |level|
             # @type var level: String
             command.severity_level = _ = level.to_sym
@@ -269,7 +326,15 @@ def process_watch
     def process_langserver
       Drivers::Langserver.new(stdout: stdout, stderr: stderr, stdin: stdin).tap do |command|
         OptionParser.new do |opts|
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+          opts.banner = <<BANNER
+Usage: steep langserver [options]
+
+Description:
+    Starts language server, which is assumed to be invoked from language client.
+
+Options:
+BANNER
+          handle_steepfile_option(opts, command)
           opts.on("--refork") { command.refork = true }
           handle_jobs_option command.jobs_option, opts
           handle_logging_options opts
@@ -301,8 +366,8 @@ def process_binstub
         opts.banner = <<BANNER
 Usage: steep binstub [options]
 
-Generate a binstub to execute Steep with setting up Bundler and rbenv/rvm.
-Use the executable for LSP integration setup.
+Description:
+    Generate a binstub which set up ruby executables and bundlers.
 
 Options:
 BANNER
@@ -373,6 +438,15 @@ def process_binstub
     end
 
     def process_version
+      OptionParser.new do |opts|
+        opts.banner = <<BANNER
+Usage: steep version [options]
+
+Description:
+    Prints Steep version.
+BANNER
+      end.parse!(argv)
+
       stdout.puts Steep::VERSION
       0
     end
@@ -385,7 +459,7 @@ def process_worker
 
           opts.on("--interaction") { command.worker_type = :interaction }
           opts.on("--typecheck") { command.worker_type = :typecheck }
-          opts.on("--steepfile=PATH") {|path| command.steepfile = Pathname(path) }
+          handle_steepfile_option(opts, command)
           opts.on("--name=NAME") {|name| command.worker_name = name }
           opts.on("--delay-shutdown") { command.delay_shutdown = true }
           opts.on("--max-index=COUNT") {|count| command.max_index = Integer(count) }

sig/steep/cli.rbs

@@ -20,6 +20,14 @@ module Steep
 
     def run: () -> Integer
 
+    interface _CommandWithSteepfile
+      def steepfile: () -> Pathname?
+
+      def steepfile=: (Pathname?) -> Pathname?
+    end
+
+    def handle_steepfile_option: (OptionParser opts, _CommandWithSteepfile) -> void
+
     def handle_logging_options: (OptionParser opts) -> void
 
     def handle_jobs_option: (Drivers::Utils::JobsOption jobs_option, OptionParser opts) -> void