我在中定义了许多功能.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
选项,但是对于这些脚本,向所有内容添加帮助标志会有些麻烦。也许这只是我应该接受的费用,但是这种:
破解似乎可以在不使源代码更难以阅读我们的编辑的情况下正常工作。
--help
选项。