From 3436bddaea90ff8ee403530891f836b2719dbf7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= Date: Sat, 29 Dec 2012 23:34:53 +0100 Subject: [PATCH] new-style documentation for most commands --- libexec/rbenv---version | 9 +++++++++ libexec/rbenv-completions | 4 +++- libexec/rbenv-exec | 16 +++++++++++++++- libexec/rbenv-help | 12 ++++++++++++ libexec/rbenv-hooks | 5 ++++- libexec/rbenv-init | 4 ++++ libexec/rbenv-prefix | 6 ++++++ libexec/rbenv-root | 1 + libexec/rbenv-shims | 3 +++ libexec/rbenv-version | 5 ++++- libexec/rbenv-version-file | 1 + libexec/rbenv-version-file-read | 1 + libexec/rbenv-version-file-write | 4 +++- libexec/rbenv-version-name | 1 + libexec/rbenv-version-origin | 1 + libexec/rbenv-versions | 4 +++- libexec/rbenv-whence | 2 +- libexec/rbenv-which | 2 +- 18 files changed, 73 insertions(+), 8 deletions(-) diff --git a/libexec/rbenv---version b/libexec/rbenv---version index aa9b829..7d65d41 100755 --- a/libexec/rbenv---version +++ b/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 diff --git a/libexec/rbenv-completions b/libexec/rbenv-completions index 4bc21a3..d5cbac3 100755 --- a/libexec/rbenv-completions +++ b/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 diff --git a/libexec/rbenv-exec b/libexec/rbenv-exec index 5c1aacd..23b75d8 100755 --- a/libexec/rbenv-exec +++ b/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 diff --git a/libexec/rbenv-help b/libexec/rbenv-help index 8f90e2b..cdb3710 100755 --- a/libexec/rbenv-help +++ b/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 diff --git a/libexec/rbenv-hooks b/libexec/rbenv-hooks index 47ee910..3221c6f 100755 --- a/libexec/rbenv-hooks +++ b/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 diff --git a/libexec/rbenv-init b/libexec/rbenv-init index 16916cd..6d53a23 100755 --- a/libexec/rbenv-init +++ b/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 diff --git a/libexec/rbenv-prefix b/libexec/rbenv-prefix index 1762f23..f68f149 100755 --- a/libexec/rbenv-prefix +++ b/libexec/rbenv-prefix @@ -1,4 +1,10 @@ #!/usr/bin/env bash +# Summary: Display prefix for a Ruby version +# Usage: rbenv prefix [] +# +# 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 diff --git a/libexec/rbenv-root b/libexec/rbenv-root index cf02c05..e632d9d 100755 --- a/libexec/rbenv-root +++ b/libexec/rbenv-root @@ -1,2 +1,3 @@ #!/usr/bin/env bash +# Summary: Display rbenv directory where versions and shims are kept echo $RBENV_ROOT diff --git a/libexec/rbenv-shims b/libexec/rbenv-shims index 6691e60..713ca5a 100755 --- a/libexec/rbenv-shims +++ b/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 diff --git a/libexec/rbenv-version b/libexec/rbenv-version index 82624ff..9ec7ac9 100755 --- a/libexec/rbenv-version +++ b/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 diff --git a/libexec/rbenv-version-file b/libexec/rbenv-version-file index e9451f4..1beea0f 100755 --- a/libexec/rbenv-version-file +++ b/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 diff --git a/libexec/rbenv-version-file-read b/libexec/rbenv-version-file-read index d6027c4..518bc47 100755 --- a/libexec/rbenv-version-file-read +++ b/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 diff --git a/libexec/rbenv-version-file-write b/libexec/rbenv-version-file-write index def9465..da6a1c9 100755 --- a/libexec/rbenv-version-file-write +++ b/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 diff --git a/libexec/rbenv-version-name b/libexec/rbenv-version-name index f65fa1d..cd1d18f 100755 --- a/libexec/rbenv-version-name +++ b/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 diff --git a/libexec/rbenv-version-origin b/libexec/rbenv-version-origin index 9b029b0..ceef0f9 100755 --- a/libexec/rbenv-version-origin +++ b/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 diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions index 3fcf1ef..5bfa72e 100755 --- a/libexec/rbenv-versions +++ b/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 diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence index 6c3486c..822ae0e 100755 --- a/libexec/rbenv-whence +++ b/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 diff --git a/libexec/rbenv-which b/libexec/rbenv-which index 7fa32a9..fe8cc28 100755 --- a/libexec/rbenv-which +++ b/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 #