Come viene utilizzata l'opzione `--description` in Fish?

Aug 22 2020

Ho notato l' --descriptionopzione 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

puffin Aug 22 2020 at 07:54

Stai tentando di chiamare la abbrfunzione con l' --descriptionopzione. L'opzione è più una sorta di "docstring" davvero semplice per lo sviluppatore, non è progettata per essere vista dall'utente finale. È un'opzione sul functioncomando, non aggiunge stringhe di aiuto o altre funzionalità alla funzione che si sta definendo.

Prendi la funzione fish fish_git_promptdefinita 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.

2 Hedy Aug 22 2020 at 07:18

L' --descriptionopzione è fornire una descrizione della funzione definita, ovviamente il comando abbr non ha un'opzione di descrizione, perché appartiene al functioncomando (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
2 mike Jan 21 2021 at 03:43

Come ha risposto @puffin, l' --descriptionopzione è 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 typeper 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.