Доступ к документации по функциям

Несмотря на то, что ниже -оптимально, следующий метод прекрасно работает в крайнем случае:

declare -A fundocs_;
doc() { fundocs_[$1]=$2; }
help_doc() { echo "$1:  ${fundocs_[$1]}"; }

doc hi_from_fun "Send a short greeting"
hi_from_fun() { echo "Hi there"; }

help_doc hi_from_fun

будет печатать документацию следующим образом:

hi_from_fun:  Send a short greeting

Обратите внимание, что первый аргумент должен совпадать с именем функции, что делает этот метод подверженным ошибкам -. Чтобы избежать ошибок в долгосрочной перспективе, можно определить документацию функции внутри тела следующим образом:

docd() { :; }  # dummy function
# for debug trap based documentation, redefined later
#  should be called with documentation as arguments
#  near the top of function body

fun2() {
    echo "Hi, I'm fun2 without documentation, just doing my job."; }

fun3() {
    docd "says hi3"
    echo "Hi, I'm fun3 with documentation, doing useful work." ; }

fun4() {
    docd "says hi4"
    echo "hi from fun4 doing other useful work"; }

Временная ловушка DEBUG может использоваться для доступа к строке документа следующим образом:

docd_() {
    # process args as documentation string
    # and return from nth level caller
    local n=${1:-2}; shift; local c=${FUNCNAME[$n]}
    local f=${1:-'echo $c: $@'}; shift
    [ -n "$c" -a "$c" != source ] && {
        eval $f
        trap "trap - DEBUG; return 2" DEBUG; } }

pdoc() {  #  redefine docd to call docd_ defined above
    docd() {
        docd_ 2 "" $@
        # default action: echo "function_name:  document_string"
    }

    for f; do $f; done  # arguments are function names

    docd() { : # so that the next call to function runs normally
    }
 }

такое, что

pdoc fun1 fun4 fun2 docd_ fun3

напечатает:

bash: fun1: command not found
fun4: says hi4
Hi, I'm fun2 without documentation, just doing my job.
fun3: says hi3

Вы можете захотеть сохранить документацию в виде массива для создания меню. Например:

prepdoc() {  # collect documentation of functions
    declare -Ag fundocs_
    docd() { docd_ 2 "fundocs_[\$c]=\"\$*\"" $@; }
    for f; do $f; done
    docd() { :; }
    declare -p fundocs_; }

prepdoc fun1 fun4 fun2 docd_ fun3

напечатает:

bash: fun1: command not found
Hi, I'm fun2 without documentation, just doing my job.
declare -A fundocs_='([fun3]="says hi3" [fun4]="says hi4" )'

где несуществующий fun1 и недокументированный fun2 являются исключениями, обычно следует избегать во время сканирования, но они были включены выше только для демонстрации того, что происходит при вызове.

Наконец, убедитесь, что каждая функция может выполнять свою обычную работу:

for f in fun1 fun4 fun2 docd_ fun3; do $f; done

и напечатает:

bash: fun1: command not found
hi from fun4 doing other useful work
Hi, I'm fun2 without documentation, just doing my job.
Hi, I'm fun3 with documentation, doing useful work.