Documentation tweaks

libexec/rbenv---version

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
 # Summary: Display the version of rbenv
 #
-# Displays the current revision info of rbenv from git if available,
+# Displays the version number of this rbenv release, including the
-# or falls back to the version of the last release.
+# current revision from git, if available.
 #
 # The format of the git revision is:
-#   ${version}-${num_commits}-g${git_sha}
+#   <version>-<num_commits>-<git_sha>
 # where `num_commits` is the number of commits since `version` was
 # tagged.
 

libexec/rbenv-completions

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv completions COMMAND [arg1 arg2...]
+# Usage: rbenv completions <command> [arg1 arg2...]
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-exec

@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 #
-# Summary: Run an executable with the right Ruby version
+# Summary: Run an executable with the selected Ruby version
 #
-# Usage: rbenv exec COMMAND [arg1 arg2...]
+# Usage: rbenv exec <command> [arg1 arg2...]
 #
 # Runs an executable by first preparing PATH so that the selected Ruby
-# version is prepended to it.
+# version's `bin' directory is at the front.
 #
-# For example, doing:
+# For example, if the currently selected Ruby version is 1.9.3-p327:
-#   RBENV_VERSION=1.9.3-p327 rbenv exec bundle install
+#   rbenv exec bundle install
 #
-# has an effect is if this was done:
+# is equivalent to:
-#   PATH=~/.rbenv/versions/1.9.3-p327:"$PATH" bundle install
+#   PATH="$RBENV_ROOT/versions/1.9.3-p327/bin:$PATH" bundle install
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-help

@@ -7,10 +7,10 @@
 # Parses and displays help contents from a command's source file.
 #
 # A command is considered documented if it starts with a comment block
-# that has at least one of the following sections: `Summary' and
+# that has a `Summary:' or `Usage:' section. Usage instructions can
-# `Usage'. Usage instructions can span multiple lines as long as
+# span multiple lines as long as subsequent lines are indented.
-# subsequent lines are indented.  Everything else in the comment is
+# The remainder of the comment block is displayed as extended
-# considered to be regular help contents.
+# documentation.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-init

@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
-# Summary: Configure shell environment for rbenv
+# Summary: Configure the shell environment for rbenv
-# Usage: rbenv init [SHELL]
+# Usage: eval "$(rbenv init - [--no-rehash] [<shell>])"
-#        rbenv init - [--no-rehash] [SHELL]
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-prefix

@@ -3,7 +3,8 @@
 # Usage: rbenv prefix [<version>]
 #
 # Displays the directory where a Ruby version is installed. If no
-# version is given, it uses the currently selected version.
+# version is given, `rbenv prefix' displays the location of the
+# currently selected version.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-rehash

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: Rehash rbenv shims (run this after installing binaries)
+# Summary: Rehash rbenv shims (run this after installing executables)
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-root

@@ -1,3 +1,3 @@
 #!/usr/bin/env bash
-# Summary: Display rbenv directory where versions and shims are kept
+# Summary: Display the root directory where versions and shims are kept
 echo $RBENV_ROOT

libexec/rbenv-version

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Summary: Show the current Ruby version and its origin
 #
-# Shows the current Ruby version and where it's set from. To obtain
+# Shows the currently selected Ruby version and how it was
-# only the version string, use `rbenv version-name'.
+# selected. To obtain only the version string, use `rbenv
+# version-name'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-version-file-read

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv version-file-read FILE
+# Usage: rbenv version-file-read <file>
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-version-file-write

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv version-file-write FILENAME VERSION
+# Usage: rbenv version-file-write <file> <version>
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-version-origin

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: Show where the current Ruby version is set from
+# Summary: Explain how the current Ruby version is set
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x