Fish 中的 `--description` 选项如何使用？

Question

我注意到该--description选项是 Fish shell 语法中函数声明的一部分。

\n

例如，/usr/share/fish/functions/abbr.fish：

\n

function abbr --description "Manage abbreviations"\n    \xe2\x80\xa6\nend\n

\n

不过，我从未见过它被使用过。以下命令都无法完成我想要完成的任务，即查看任何给定函数的描述（前提是已定义）：

\n

> abbr --description\nabbr: Unknown option \xe2\x80\x9c--description\xe2\x80\x9d\n/usr/share/fish/functions/abbr.fish (line 6): \n    argparse -n abbr $options -- $argv\n    ^\nin function 'abbr' with arguments '--description'\n> help --description\nhelp: Unknown option \xe2\x80\x9c--description\xe2\x80\x9d\n/usr/share/fish/functions/help.fish (line 3): \n    argparse -n help --max-args=1 $options -- $argv\n    ^\nin function 'help' with arguments '--description'\n> help description # opens file:///usr/share/doc/fish/index.html in a browser (same functionality as `help`)\n> help abbr # opens file:///usr/share/doc/fish/cmds/abbr.html in a browser (only works for built-in functions)\n

\n

我在文档中没有看到有关此选项的任何内容。如果有的话，请指出我。

\n

Answer 1

该--description选项是为您的函数定义添加文档字符串。

文档字符串有助于检查其他开发人员的代码。它对于您的函数的用户也很有用，并且实际上被设计为让用户在多个地方看到。

• 在TAB完成菜单中
• type在函数的输出中
• functions -vD 在funcname的输出中（详细信息）

示例，使用这个简单的函数定义：

mjl@jazz ~> function ... -d 'Go up two directory levels.'
                ../../
            end

打TAB：

这是|最有用的目的 。输入 后，Fish 显示完成情况如下（它添加了第三个）：--description-d..TAB.

mjl@jazz ~> ...
..  ...  (Go up two directory levels.)  ../  (Directory, 160B)

出现描述，让用户一看就知道是什么... 意思。

列出函数：

mjl@jazz ~> type ...
... is a function with definition
function ... --description 'Go up two directory levels.'
../../
end

显示函数的详细信息：

mjl@jazz ~> functions -vD ...
stdin
n/a
0
scope-shadowing
Go up two directory levels.