![在旨在交互使用的函数中显示使用注释](https://linux22.com/image/90201/%E5%9C%A8%E6%97%A8%E5%9C%A8%E4%BA%A4%E4%BA%92%E4%BD%BF%E7%94%A8%E7%9A%84%E5%87%BD%E6%95%B0%E4%B8%AD%E6%98%BE%E7%A4%BA%E4%BD%BF%E7%94%A8%E6%B3%A8%E9%87%8A.png)
我在 my 中定义了许多函数.bashrc
,旨在在终端中交互使用。我通常在它们之前添加一条描述其预期用途的评论:
# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
...
}
如果浏览源代码,这很好,但最好type
在终端中运行以快速提醒该函数的作用。然而,这(可以理解)不包括评论:
$ type foo
foo is a function
foo ()
{
...
}
这让我想到“如果这些评论持续存在以便type
可以显示出来,那不是很好吗?”本着 Python 的精神文档字符串我想出了这个:
foo() {
: Usage: foo [bar]
: "Foo's a bar into a baz"
...
}
$ type foo
foo is a function
foo ()
{
: Usage: foo [bar];
: "Foo's a bar into a baz";
...
}
现在用法已包含在type
输出中!当然,正如您所看到的,引用成为一个容易出错的问题,但当它起作用时,它会带来更好的用户体验。
所以我的问题是,这是一个糟糕的主意吗?是否有更好的替代方案(例如函数的man
/ info
)来为 Bash 函数的用户提供额外的上下文?
理想情况下,我仍然希望使用说明位于函数定义附近,以便查看源代码的人们也能受益,但如果有“正确”的方法来做到这一点,我愿意接受替代方案。
编辑这些都是相当简单的辅助函数,我只是想以交互方式获得一些额外的上下文。当然,对于解析标志的更复杂的脚本,我会添加一个--help
选项,但对于这些脚本,向所有内容添加帮助标志会有些麻烦。也许这只是我应该接受的成本,但这种:
黑客似乎工作得相当好,并且不会使源代码更难以阅读我们的编辑。
答案1
我不认为只有一种好方法可以做到这一点。
如果用户提供-h
或--help
作为选项,许多函数、脚本和其他可执行文件都会提供帮助消息:
$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}
例如:
$ foo -h
Usage: foo [bar]
Foo's a bar into a baz
$ foo --help
Usage: foo [bar]
Foo's a bar into a baz
答案2
我从来没有相当说服自己冒险尝试并使用:
命令作为伪注释。特别是,我一直担心“注释”实际上是要评估的参数,并且可能会产生副作用(或者只是破坏事物,例如错误'
)。我仍然喜欢这个想法的简单性,但还没有发现这种权衡是合理的。
我对通过标志或类似内容提供使用文本的犹豫--help
一直是随之而来的问题。一旦你开始接受标志,你很快就会进入成熟的参数解析,这通常(在 Bash 中)需要相当多的样板文件。
为了部分弥补这一差距,我汇集了小实用程序getopts
为了减少这个样板文件而进行包装。它仍然占用几行,所以我不会在其他很小的函数中使用它,但它比直接使用要简洁得多getopts
。这是带有标志的示例用法-h
(getopts
仅支持单字母选项):
foo() {
local _usage='foo [-a] [-b] [-f val] [-v val] [args ...]'
eval "$(parse_opts 'f:v:abh')"
if (( h )); then
echo "Usage: $_usage"
return 0
fi
echo "f=$f v=$v a=$a b=$b -- $#: $*"
}