主页 / unix / 问题 / 511073
Accepted
alias
Asked: 2019-04-08 08:44:06 +0800 CST

访问函数文档

  • 772

有没有办法在 Bash 中访问文档字符串？如何在 Bash 中的函数定义中包含文档字符串？

更具体地说，如何向以下函数添加和访问文档字符串？

    funky() {
    echo "Violent and funky!"
    }
bash shell-script

2 个回答

  1. 虽然次优，但以下方法在紧要关头可以正常工作：

    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.
    • 2
  2. Best Answer

    如果您的意思是“Bash 相当于 Python 的文档字符串”，恐怕我不得不让您失望，因为没有这样的东西。

    但是..我必须说，实现“文档字符串”功能的等效功能将成为一项非常有趣的作业，以便学习 Bash 的可编程完成功能以及如何覆盖内置命令，例如help显示此类“文档字符串”或正常的 builtinhelp的输出。

    • 1

相关问题