zsh compadd - how to specify argument's description?

Question

With _arguments I can do _arguments {-h,--help}'[Show help]', but how to specify 'Show help' message in compadd parameters? Cannot find that in documentation

Answer 1

There is no easy way to do that with just compadd. That's why _arguments calls _describe under the hood. You might want to look into that function, if you want to customize things a bit more than _arguments allows.

However, if you really want to do it by making calls to compadd: What _describe does is add empty (that is, unselectable) completions with the -E option to compadd and then sets descriptions for them with the -d. Laying them out correctly, though, is a major PITA. That's why _describe uses a builtin function compdescribe for this—which is unfortunately poorly documented.

You're probably better off just sticking to _arguments and/or _describe.

Answer 2

I know this question is old. I had this question recently and this is how I solved it.

function _foo {
  
  local -a _descriptions _values

  _descriptions=(
    'foo -- Description of foo'
    'bar -- Description of bar'
    'baz -- Description of baz'
  )

  _values=(
    'bar'
    'foo'
    'baz'
  )

  # Vertical window completion
  compadd -d _descriptions -a _values
  #$~ foo
  # bar -- Description of bar
  # baz -- Description of baz
  # foo -- Description of foo

  # Horizontal completion
  # compadd -d _descriptions -a _values
  #$~ foo
  # bar -- Description of bar  baz -- Description of baz  foo -- Description of foo
}

compdef _foo foo

Note: that this works only with arrays. If you have a string, you must convert it to an array