Fishの `--description`オプションはどのように使用されますか？

Question

--descriptionFishシェル構文の関数宣言の一部としてこのオプションに気づきました。

例/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)

このオプションについては、ドキュメントで何も見ていません。そこにあるなら、私にそれを指摘してください。

Answer 1

オプションを指定してabbr関数を呼び出そうとしてい--descriptionます。このオプションは、開発者にとっては非常に単純な「docstring」のようなものであり、エンドユーザーに表示されるようには設計されていません。functionコマンドのオプションであり、定義されている関数にヘルプ文字列やその他の機能を追加するものではありません。

でfish_git_prompt定義された魚関数を取り/usr/share/fish/functions/fish_git_prompt.fishます。その完全な定義はfunction fish_git_prompt --description "Prompt function for Git"であり、説明は目的の非常に簡単な説明を提供します。説明はかなり反復的で冗長すぎますが、あいまいな可能性のある短い関数名の場合に役立ちます。

Answer 2

--descriptionオプションはもちろん、それが属しているため、略称コマンドは、記述オプションを持っていない、定義された関数の説明を提供することでfunction、コマンド（及び略称は、このようなオプションがありません）

魚のドキュメントを参照してください：

• https://fishshell.com/docs/current/cmds/function.html#description
• https://fishshell.com/docs/current/cmds/abbr.html#options

Answer 3

@puffinが答えたように、--descriptionオプションは関数定義にdocstringを追加することです。

しかし、それは単なる「開発者向け」のものよりもはるかに便利であり、実際には、いくつかの場所でユーザーに表示されるように設計されています。

• ではTABの終了メニュー
• type関数の出力で
• functions -vD funcnameの出力（v erbose D etails）

この単純な関数定義を使用した例：

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

タブを押す：

これは|の最も有用な目的です--description。-d。入力した後。。TAB、これはFishが完了を表示する方法です（3番目を追加しました.）：

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.