Come viene utilizzata l'opzione `--description` in Fish?
Ho notato l' --description
opzione come parte delle dichiarazioni di funzione nella sintassi della shell di pesce.
Ad esempio /usr/share/fish/functions/abbr.fish
:
function abbr --description "Manage abbreviations"
…
end
Comunque non l'ho mai visto usato. Nessuno dei seguenti comandi esegue ciò che sto cercando di ottenere, ovvero visualizzare la descrizione di una determinata funzione (a condizione che sia definita):
> 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)
Non ho visto nulla su questa opzione nella documentazione. Se c'è, per favore indicamelo.
Risposte
Stai tentando di chiamare la abbr
funzione con l' --description
opzione. L'opzione è più una sorta di "docstring" davvero semplice per lo sviluppatore, non è progettata per essere vista dall'utente finale. È un'opzione sul function
comando, non aggiunge stringhe di aiuto o altre funzionalità alla funzione che si sta definendo.
Prendi la funzione fish fish_git_prompt
definita in /usr/share/fish/functions/fish_git_prompt.fish
. La sua definizione completa è function fish_git_prompt --description "Prompt function for Git"
e la descrizione fornisce una spiegazione molto breve dello scopo. Le descrizioni sono piuttosto ripetitive ed eccessivamente prolisse, ma sarebbero più utili per nomi di funzioni brevi che potrebbero essere ambigui.
L' --description
opzione è fornire una descrizione della funzione definita, ovviamente il comando abbr non ha un'opzione di descrizione, perché appartiene al function
comando (e abbr non ha tale opzione)
Vedi i documenti sui pesci:
- https://fishshell.com/docs/current/cmds/function.html#description
- https://fishshell.com/docs/current/cmds/abbr.html#options
Come ha risposto @puffin, l' --description
opzione è aggiungere una docstring per la definizione della tua funzione.
Ma è molto più utile di qualcosa "per lo sviluppatore", ed è infatti progettato per essere visto dall'utente, in più punti.
- Nei menu di completamento TAB
- Nell'output di
type
per una funzione - Nell'output di
functions -vD
funcname ( v erbose D etails )
Esempi, utilizzando questa semplice definizione di funzione:
mjl@jazz ~> function ... -d 'Go up two directory levels.'
../../
end
Colpire TAB:
Questo è lo scopo più utile di --description
| -d
. Dopo aver digitato . . TAB , ecco come Fish mostra i completamenti (ha aggiunto il terzo .
):
mjl@jazz ~> ...
.. ... (Go up two directory levels.) ../ (Directory, 160B)
Viene visualizzata la descrizione, in modo che l'utente possa capire a colpo d'occhio qual ...
è il significato di .
Elencando la funzione:
mjl@jazz ~> type ...
... is a function with definition
function ... --description 'Go up two directory levels.'
../../
end
Mostra i dettagli della funzione:
mjl@jazz ~> functions -vD ...
stdin
n/a
0
scope-shadowing
Go up two directory levels.