Improve syntax for inline documentation and allow for multi-line usage

libexec/rbenv-commands

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv commands [ --sh | --no-sh ]
-# Summary: List all rbenv commands
+# Summary: List all available rbenv commands
+# Usage: rbenv commands [--sh|--no-sh]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-global

@@ -1,4 +1,17 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the global Ruby version
+#
+# Usage: rbenv global <version>
+#
+# Sets the global Ruby version. You can override the global version at
+# any time by setting a directory-specific version with `rbenv local'
+# or by setting the `RBENV_VERSION' environment variable.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-help

@@ -2,112 +2,129 @@
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
-# content from single commented line marked with a word such as "Usage" or "Summary"
-extract_line() {
-  grep "^# ${1}:" "$2" | head -1 | cut -d ' ' -f3-
+command_path() {
+  local command="$1"
+  command -v rbenv-"$command" || command -v rbenv-sh-"$command" || true
 }
 
-# content of multiple consecutive commented lines starting with a word such as "Help"
-extract_section() {
-  sed -En "/^# ${1}: /,/^[^#]/s/^# ?//p" "$2" | sed "1s/${1}: //"
+extract_initial_comment_block() {
+  sed -ne "
+    /^#/ !{
+      q
+    }
+
+    s/^#$/# /
+
+    /^# / {
+      s/^# //
+      p
+    }
+  "
 }
 
-# print aligned command names with help summary
-print_summary() {
-  if [ ! -h "$1" ]; then
-    local summary=$(extract_line Summary "$1")
-    if [ -n "$summary" ]; then
-      local name=$(basename "$1")
-      echo "${name#rbenv-}" | awk '{ printf "   %-14s   ", $1 }'
-      echo -n $summary
-      echo
-    else
-      return 1
-    fi
+collect_documentation() {
+  awk '
+    /^Summary:/ {
+      summary = substr($0, 10)
+      next
+    }
+
+    /^Usage:/ {
+      reading_usage = 1
+      usage = usage "\n" $0
+      next
+    }
+
+    /^( *$|       )/ && reading_usage {
+      usage = usage "\n" $0
+      next
+    }
+
+    /^([^ ]|$)/ {
+      reading_usage = 0
+      help = help "\n" $0
+    }
+
+    function escape(str) {
+      gsub(/[`\\$"]/, "\\\\&", str)
+      return str
+    }
+
+    function trim(str) {
+      gsub(/^\n*/, "", str)
+      gsub(/\n*$/, "", str)
+      return str
+    }
+
+    END {
+      if (usage || summary) {
+        print "summary=\"" escape(summary) "\""
+        print "usage=\"" escape(trim(usage)) "\""
+        print "help=\"" escape(trim(help)) "\""
+      }
+    }
+  '
+}
+
+documentation_for() {
+  local filename="$(command_path "$1")"
+  if [ -n "$filename" ]; then
+    extract_initial_comment_block < "$filename" | collect_documentation
   fi
 }
 
-print_help() {
-  local usage="$(extract_line Usage "$1")"
-  local halp="$(extract_section Help "$1")"
-  [ -z "$halp" ] && halp="$(extract_line Summary "$1")"
+print_summary() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
 
-  if [ -n "$usage" ]; then
-    echo usage: $usage
-    [ -n "$halp" ] && echo && echo "$halp"
+  if [ -n "$summary" ]; then
+    printf "   %-9s   %s\n" "$command" "$summary"
   else
-    echo "Sorry, this command isn't documented yet." >&2
     return 1
   fi
 }
 
 print_summaries() {
-  for command in $1; do
-    print_summary "$(command -v rbenv-"$command")"
+  for command; do
+    print_summary "$command"
   done
 }
 
-print_set_version() {
-  echo "<version> should be a string matching a Ruby version known by rbenv."
+print_help() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -n "$help" ] || help="$summary"
 
-  local versions="$(rbenv-versions --bare)"
-  if [ -z "$versions" ]; then
-    echo "There are currently no Ruby versions installed for rbenv."
+  if [ -n "$usage" ]; then
+    echo "$usage"
+    if [ -n "$help" ]; then
+      echo
+      echo "$help"
+      echo
+    fi
   else
-    echo "The currently installed Ruby versions are:"
-    echo "$versions" | sed 's/^/  /'
+    echo "Sorry, this command isn't documented yet." >&2
+    return 1
   fi
-
-  echo
-  echo "The special version string 'system' will use your default system Ruby."
 }
 
-case "$1" in
-"") echo "usage: rbenv <command> [<args>]
-
-Some useful rbenv commands are:
-$(print_summaries "commands rehash global local shell version versions which whence")
-
-See 'rbenv help <command>' for information on a specific command.
-For full documentation, see: https://github.com/sstephenson/rbenv#readme"
-;;
-global) echo "usage: rbenv global <version>
-
-Sets the global Ruby version. You can override the global version at
-any time by setting a directory-specific version with \`rbenv local'
-or by setting the RBENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-local) echo "usage: rbenv local <version>
-       rbenv local --unset
-
-Sets the local directory-specific Ruby version by writing the version
-name to a file named '.rbenv-version'.
-
-When you run a Ruby command, rbenv will look for an '.rbenv-version'
-file in the current directory and each parent directory. If no such
-file is found in the tree, rbenv will use the global Ruby version
-specified with \`rbenv global', or the version specified in the
-RBENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-shell) echo "usage: rbenv shell <version>
-       rbenv shell --unset
-
-Sets a shell-specific Ruby version by setting the 'RBENV_VERSION'
-environment variable in your shell. This version overrides both
-project-specific versions and the global version.
-
-$(print_set_version)"
-;;
-*)
-  command_path="$(command -v "rbenv-$1" || true)"
-  if [ -n "$command_path" ]; then
-    print_help "$command_path"
+if [ -z "$1" ]; then
+  rbenv---version
+  echo "Usage: rbenv <command> [<args>]"
+  echo
+  echo "Some useful rbenv commands are:"
+  print_summaries commands rehash global local shell version versions which whence
+  echo
+  echo "See \`rbenv help <command>' for information on a specific command."
+  echo "For full documentation, see: https://github.com/sstephenson/rbenv#readme"
+else
+  command="$1"
+  if [ -n "$(command_path "$command")" ]; then
+    print_help "$command"
   else
-    echo "rbenv: no such command \`$1'" >&2
+    echo "rbenv: no such command \`$command'" >&2
     exit 1
   fi
-esac
+fi

libexec/rbenv-local

@@ -1,4 +1,23 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the local directory-specific Ruby version
+#
+# Usage: rbenv local <version>
+#        rbenv local --unset
+#
+# Sets the local directory-specific Ruby version by writing the version
+# name to a file named `.rbenv-version'.
+#
+# When you run a Ruby command, rbenv will look for an `.rbenv-version'
+# file in the current directory and each parent directory. If no such
+# file is found in the tree, rbenv will use the global Ruby version
+# specified with `rbenv global', or the version specified in the
+# RBENV_VERSION environment variable.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-rehash

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

libexec/rbenv-sh-shell

@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the shell-specific Ruby version
+#
+# Usage: rbenv shell <version>
+#        rbenv shell --unset
+#
+# Sets a shell-specific Ruby version by setting the `RBENV_VERSION'
+# environment variable in your shell. This version overrides both
+# project-specific versions and the global version.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-version

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

libexec/rbenv-versions

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv versions [--bare]
 # Summary: List all Ruby versions known by rbenv
+# Usage: rbenv versions [--bare]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-whence

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv whence [--path] COMMAND
 # Summary: List all Ruby versions with the given command installed
+# Usage: rbenv whence [--path] COMMAND
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-which

@@ -1,8 +1,12 @@
 #!/usr/bin/env bash
-# Usage: rbenv which COMMAND
-# Summary: Display full path to a binary
-# Help: Displays the full path to the binary that rbenv will execute when you
+#
+# Summary: Display the full path to a binary
+#
+# Usage: rbenv which <command>
+#
+# Displays the full path to the binary that rbenv will execute when you
 # run the given command.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x