Clarify help text of some commands (#1567)

libexec/rbenv-commands

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # Summary: List all available rbenv commands
 # Usage: rbenv commands [--sh|--no-sh]
+#
+# List names of all rbenv commands, including 3rd-party ones found in the
+# PATH or in rbenv plugins. With `--sh`, list only shell commands.
+#
+# This functionality is mainly meant for scripting. To see usage help for
+# rbenv, run `rbenv help`.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-exec

@@ -2,7 +2,7 @@
 #
 # Summary: Run an executable with the selected Ruby version
 #
-# Usage: rbenv exec <command> [arg1 arg2...]
+# Usage: rbenv exec <command> [<args>...]
 #
 # Runs an executable by first preparing PATH so that the selected Ruby
 # version's `bin' directory is at the front.

libexec/rbenv-help

@@ -164,8 +164,11 @@ if [ -z "$1" ] || [ "$1" == "rbenv" ]; then
   echo "Usage: rbenv <command> [<args>...]"
   [ -n "$usage" ] && exit
   echo
-  echo "Some useful rbenv commands are:"
-  print_summaries commands local global shell install uninstall rehash version versions which whence
+  echo "Commands to manage available Ruby versions:"
+  print_summaries versions install uninstall rehash
+  echo
+  echo "Commands to view or change the current Ruby version:"
+  print_summaries version local global shell
   echo
   echo "See \`rbenv help <command>' for information on a specific command."
   echo "For full documentation, see: https://github.com/rbenv/rbenv#readme"

libexec/rbenv-rehash

@@ -1,5 +1,16 @@
 #!/usr/bin/env bash
-# Summary: Rehash rbenv shims (run this after installing executables)
+# Summary: Regenerate rbenv shims
+#
+# Regenerate shims for every Ruby executable in `$RBENV_ROOT/versions/*/bin'
+# and write them to the `$RBENV_ROOT/shims' directory. A shell environment
+# properly set up for rbenv will have this shims directory in PATH, which is
+# the core mechanism for Ruby version switching.
+#
+# Running rbenv rehash should only be necessary after installing new Ruby
+# versions or gems. Note that this is sometimes done automatically: the
+# `rbenv install' command from the ruby-build plugin runs rehash after
+# every successful installation, and a RubyGems plugin that ships with
+# rbenv runs rehash after every `gem install' command.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

test/help.bats

@@ -6,7 +6,7 @@ load test_helper
   run rbenv-help
   assert_success
   assert_line "Usage: rbenv <command> [<args>...]"
-  assert_line "Some useful rbenv commands are:"
+  assert_line "Commands to manage available Ruby versions:"
 }
 
 @test "usage flag" {