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

【问题标题】：How is the `--description` option in Fish used?Fish 中的 `--description` 选项如何使用？
【发布时间】：2020-08-21 23:47:15
【问题描述】：

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

例如/usr/share/fish/functions/abbr.fish:

function abbr --description "Manage abbreviations"
    …
end

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

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

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

【问题讨论】：

您可能会猜到，该选项只允许提供描述。奇怪的是您收到了该定义的错误，它适用于版本 3.1.2，您运行的是什么版本的鱼？
我也在运行 3.1.2。我也应该发布 ~/.config/fish/config.fish 吗？我不认为那里有任何东西会破坏它。
哦，我明白你的困惑了。您正在尝试使用 description 选项调用 abbr 函数。对于开发人员来说，该选项更像是一种非常简单的“文档字符串”，它不是为最终用户查看而设计的。它是function 命令上的一个选项，它不会向正在生成的函数添加一个
如果它不被查看，为什么要把它传递给function呢？它实际上是一个特殊的评论吗？
基本上，它是为开发人员准备的。例如函数function fish_git_prompt --description "Prompt function for Git"，它对函数的用途有非常简短的描述。它确实看起来过于冗长和重复，除非它解决了一个模棱两可的函数名称

标签： fish

【解决方案1】：

正如@puffin 回答的那样，--description 选项是为您的函数定义添加一个docstring。

但它不仅仅是“为开发者”提供的东西更有用，而且实际上是为了让用户在多个地方看到。

在TAB完成菜单中
在函数的type 的输出中
在functions -vD funcname 的输出中（v erbose D etails）

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

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

点击TAB：

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

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.

【讨论】：

【解决方案2】：

--description选项是提供定义函数的描述，当然abbr命令没有描述选项，因为它属于function命令（而abbr没有这个选项）

查看鱼文档：

【讨论】：

我看到列出的选项，但我看不出它的用途。另外，我没有重新定义abbr；我只是从内置目录中复制过来的。

【解决方案3】：

您正在尝试使用 --description 选项调用 abbr 函数。对于开发人员而言，该选项更像是一种非常简单的“文档字符串”，它并非旨在让最终用户看到。它是function 命令的一个选项，它不会向正在定义的函数添加任何帮助字符串或其他功能。

取/usr/share/fish/functions/fish_git_prompt.fish中定义的鱼函数fish_git_prompt。它的完整定义是function fish_git_prompt --description "Prompt function for Git"，描述提供了一个非常简短的目的说明。这些描述非常重复且过于冗长，但对于可能模棱两可的短函数名称会更有用。

【讨论】：