new-style documentation for most commands

libexec/rbenv---version

@@ -1,4 +1,13 @@
 #!/usr/bin/env bash
+# Summary: Display the version of rbenv
+#
+# Displays the current revision info of rbenv from git if available, or falls
+# back to the version of the last release.
+#
+# The format of the git revision is:
+#   ${version}-${num_commits}-g${git_sha}
+# where `num_commits` is the number of commits since `version` was tagged.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-completions

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
+# Usage: rbenv completions COMMAND [arg1 arg2...]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
 COMMAND="$1"
 if [ -z "$COMMAND" ]; then
-  echo "usage: rbenv completions COMMAND [arg1 arg2...]" >&2
+  rbenv-help --usage completions >&2
   exit 1
 fi
 

libexec/rbenv-exec

@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Run an executable with the right Ruby version
+#
+# Usage: rbenv exec COMMAND [arg1 arg2...]
+#
+# Runs an executable by first preparing PATH so that the selected Ruby version
+# is prepended to it.
+#
+# For example, doing:
+#   RBENV_VERSION=1.9.3-p327 rbenv exec bundle install
+#
+# has an effect is if this was done:
+#   PATH=~/.rbenv/versions/1.9.3-p327:"$PATH" bundle install
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -11,7 +25,7 @@ export RBENV_VERSION="$(rbenv-version-name)"
 RBENV_COMMAND="$1"
 
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv exec COMMAND [arg1 arg2...]" >&2
+  rbenv-help --usage exec >&2
   exit 1
 fi
 

libexec/rbenv-help

@@ -1,4 +1,16 @@
 #!/usr/bin/env bash
+#
+# Summary: Display help for a command
+#
+# Usage: rbenv help [--usage] COMMAND
+#
+# 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 `Usage'. Usage
+# instructions can span multiple lines as long as subsequent lines are indented.
+# Everything else in the comment is considered to be regular help contents.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-hooks

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List hook scripts for a rbenv command
+# Usage: rbenv hooks COMMAND
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -12,7 +15,7 @@ fi
 
 RBENV_COMMAND="$1"
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv hooks COMMAND" >&2
+  rbenv-help --usage hooks >&2
   exit 1
 fi
 

libexec/rbenv-init

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Summary: Configure shell environment for rbenv
+# Usage: rbenv init [SHELL]
+#        rbenv init - [--no-rehash] [SHELL]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-prefix

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+# Summary: Display prefix for a Ruby version
+# Usage: rbenv prefix [<version>]
+#
+# Displays the directory where a Ruby version is installed. If no version is
+# given, it uses the currently selected version.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-root

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

libexec/rbenv-shims

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List existing rbenv shims
+# Usage: rbenv shims [--short]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-version

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

libexec/rbenv-version-file

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Detect the file that sets the current rbenv version
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-version-file-read

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

libexec/rbenv-version-file-write

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv version-file-write FILENAME VERSION
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -6,7 +8,7 @@ RBENV_VERSION_FILE="$1"
 RBENV_VERSION="$2"
 
 if [ -z "$RBENV_VERSION" ] || [ -z "$RBENV_VERSION_FILE" ]; then
-  echo "usage: rbenv version-file-write FILENAME VERSION" >&2
+  rbenv-help --usage version-file-write >&2
   exit 1
 fi
 

libexec/rbenv-version-name

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

libexec/rbenv-version-origin

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

libexec/rbenv-versions

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
-# Summary: List all Ruby versions known by rbenv
+# Summary: List all Ruby versions available to rbenv
 # Usage: rbenv versions [--bare]
+#
+# Lists all Ruby versions found in `$RBENV_ROOT/versions/*'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

libexec/rbenv-whence

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: List all Ruby versions with the given command installed
+# Summary: List all Ruby versions that contain the given executable
 # Usage: rbenv whence [--path] COMMAND
 
 set -e

libexec/rbenv-which

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# Summary: Display the full path to a binary
+# Summary: Display the full path to an executable
 #
 # Usage: rbenv which <command>
 #