如何使用 Fish 中的 `--description` 选项？
How is the `--description` option in Fish used?
我注意到 --description 选项作为 Fish shell 语法中函数声明的一部分。
例如，/usr/share/fish/functions/abbr.fish:
function abbr --description "Manage abbreviations"
…
end
但是，我从未见过它被使用过。 None 以下命令执行我想要完成的操作，即查看任何给定函数的描述（前提是它已定义）：
> 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)
我在文档中没有看到关于此选项的任何内容。如果有，请指点一下。
--description选项是提供定义函数的描述，当然abbr命令没有描述选项，因为它属于function命令（而abbr没有'没有这样的选择)
查看鱼文档：
您正在尝试使用 --description 选项调用 abbr 函数。该选项对于开发人员来说更像是一种非常简单的“文档字符串”，它不是为最终用户设计的。它是 function 命令上的一个选项，它不会向正在定义的函数添加任何帮助字符串或其他功能。
以 /usr/share/fish/functions/fish_git_prompt.fish 中定义的 fish 函数 fish_git_prompt 为例。它的完整定义是function fish_git_prompt --description "Prompt function for Git"，描述提供了一个非常简短的目的解释。描述相当重复且过于冗长，但对于可能含糊不清的简短函数名称会更有用。
正如@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.
我注意到 --description 选项作为 Fish shell 语法中函数声明的一部分。
例如，/usr/share/fish/functions/abbr.fish:
function abbr --description "Manage abbreviations"
…
end
但是，我从未见过它被使用过。 None 以下命令执行我想要完成的操作，即查看任何给定函数的描述（前提是它已定义）：
> 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)
我在文档中没有看到关于此选项的任何内容。如果有，请指点一下。
--description选项是提供定义函数的描述，当然abbr命令没有描述选项，因为它属于function命令（而abbr没有'没有这样的选择)
查看鱼文档：
您正在尝试使用 --description 选项调用 abbr 函数。该选项对于开发人员来说更像是一种非常简单的“文档字符串”，它不是为最终用户设计的。它是 function 命令上的一个选项，它不会向正在定义的函数添加任何帮助字符串或其他功能。
以 /usr/share/fish/functions/fish_git_prompt.fish 中定义的 fish 函数 fish_git_prompt 为例。它的完整定义是function fish_git_prompt --description "Prompt function for Git"，描述提供了一个非常简短的目的解释。描述相当重复且过于冗长，但对于可能含糊不清的简短函数名称会更有用。
正如@puffin 回答的那样，--description 选项是为您的函数定义添加一个docstring。
但它比“为开发人员”提供的东西要有用得多，而且实际上在几个地方被设计为被用户看到。
- 在TAB完成菜单
- 在函数
type的输出中 - 在
functions -vDfuncname 的输出中 ( 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.