Adding a description to a function later on does not work for me

[sabinem]

fish, version 2.7.1-1246-geca4273f-dirty

1. I struggle with the following problem:

I have made a function:

function hello --argument name
           echo hello $name
       end

Now I notice that I forgot to add a -d option for describing it.

• the `function hello -d "some description" will not bring my function back, I would have to write it completely from scratch

• funced has no -d option

• functions -d DESCRIPTION FUNCTION (see https://fishshell.com/docs/current/commands.html#functions: this sounds great but does not work for me:

-d DESCRIPTION or --description=DESCRIPTION changes the description of this function.

> functions -d "hello function" hello
functions: Unknown option '-d'

       functions

   Synopsis
       functions [ -a | --all ] [ -n | --names ]
       functions [ -D | --details ] [ -v ] FUNCTION
       functions -c OLDNAME NEWNAME
       functions -d DESCRIPTION FUNCTION
       functions [ -e | -q ] FUNCTIONS...

functions: Type 'help functions' for related documentation

To me this seems like a bug. There should be a possibility to add a description to a function later on. Am I doing anything wrong here? Help on this is appreciated.

2. One more remark:

-D or --details reports the path name where each function is defined or could be autoloaded, stdin if the function was defined interactively or on the command line or by reading stdin, and n/a if the function isn't available. If the --verbose option is also specified then five lines are written:
- the pathname as already described,
- autoloaded, not-autoloaded or n/a,
- the line number within the file or zero if not applicable,
- scope-shadowing if the function shadows the vars in the calling function (the normal case if it wasn't defined with --no-scope-shadowing), else no-scope-shadowing, or n/a if the function isn't defined,
- the function description minimally escaped so it is a single line or n/a if the function isn't defined.

This does work, but the output is hard to read:

> functions -vD  hello
/Users/sabinemaennel/.config/fish/functions/hello.fish
autoloaded
2
scope-shadowing
n/a

I think this would improve a lot if the fields would have names in front of them such as:

> functions -vD  hello
path: /Users/sabinemaennel/.config/fish/functions/hello.fish
loaded: autoloaded
line numbers: 2
scope: scope-shadowing
description: n/a

Otherwise the output cannot be read without crossreading with the documentation. What do you think about this proposed change?

[ridiculousfish]

The functions -d flag was a simple oversight. Fixed thanks! Note that functions --description was properly implemented and can be used.

[ridiculousfish]

+1 to your named fields idea if you or anyone wants to do it!

[kartoffelsup]

• the function description minimally escaped so it is a single line or n/a if the function isn't defined.

Sounds like a documentation oversight. It seems it can also be n/a if no description was given.