completion implementation woes

[Roman Neuhauser <neuhauser@sigpipe.cz>]

hello,

i have difficult time with completion for a git subcommand i wrote,
and would appreciate a little help.

the tool has this synopsis (all options have one-letter equivalents,
only the long versions are listed here to keep it simpler):

  git [git-opts] dirs -h | --help
  git [git-opts] dirs activate REPO
  git [git-opts] dirs active [--full | --relative | --short]
  git [git-opts] dirs clone [--no-activate] URL [REPO]
  git [git-opts] dirs init [--no-activate] REPO
  git [git-opts] dirs list [--full | --relative | --short]

the option handling code requires options in places indicated by
the synopsis (`git dirs init stuff --no-activate` is an error).

below is my failed attempt at implementing the completion, with
descriptions of and questions about its behaviors.  the code largely
cargo-cults Completion/Unix/_cvs as seen in zsh-5.2, yet it doesn't
work beyond _git-dirs-_verb (_arguments -> _describe).
_arguments -> _arguments chains behave strangely.

i'm apparently missing something about _arguments: _cvs chains
_arguments calls in the same way, why doesn't mine work?

  #compdef git-dirs
  #description manage multiple git dirs
  # vim: ts=2 sts=2 sw=2 et fdm=marker cms=\ #\ %s

  function _git-dirs # {{{
  {
    local -A opt_args
    local -a state
    _git-dirs-_args \
      - '(help)' \
        '-h[display usage]' \
        '--help[display man page]' \
      - 'command' \
        ":command:_git-dirs-_verb" \
        "*:option or operand:_git-dirs-_verb-arg"
  } # }}}

  function _git-dirs-_verb # {{{
  {
    local -a _commands=(
      activate:'Associate $PWD with REPO'
      active:'Show the currently active repository'
      clone:'Clone URL into .git-dirs/repo.d/REPO'
      init:'Initialize a repository in .git-dirs/repo.d/REPO'
      list:'List repositories in .git-dirs/repo.d'
    )
    _describe -t commands command _commands
  } # }}}

  function _git-dirs-_verb-arg # {{{
  {
    local cmd=$words[2]
    local rv=1

    :; _call_function rv _git-dirs-$cmd \
    || _message -r "unknown command: $cmd"
    :; return $rv
  } # }}}

  function _git-dirs-_args # {{{
  {
    _arguments -S -s : "$@"
  } # }}}

  # $ git dirs activate <TAB>
  # #### no more arguments ####

  function _git-dirs-activate # {{{
  {
    local -a repos=(.git-dirs/repo.d/*(/N:t))
    _git-dirs-_args \
      ":REPO:($repos)"
  } # }}}

  # $ git dirs clone <TAB>
  # #### REPO ####

  # why does it expect REPO?  what happened to URL?

  function _git-dirs-clone # {{{
  {
    _git-dirs-_args \
      {-N,--no-activate}'[Do not activate the repository]' \
      ':URL: ' \
      '::REPO: '
  } # }}}

  # $ git dirs init <TAB> (inserts '-')
  # #### option ####
  --no-activate  -N  -- Do not activate the repository                                                   

  # why does it insert a dash? `git dirs clone <TAB>` has
  # a very similar _arguments call and does something else.

  # $ git dirs init -N<TAB>
  # #### no more arguments ####

  # why all the <NOTHING>s below?  what makes them different
  # from the "no more arguments" cases? (<NOTHING> means no output
  # from the completion system)

  # $ git dirs init -N <TAB>
  # <NOTHING>

  # $ git dirs init --no-activate<TAB> (inserts space)
  # <NOTHING>

  # $ git dirs init --no-activate <TAB>
  # <NOTHING>

  function _git-dirs-init # {{{
  {
    _git-dirs-_args \
      {-N,--no-activate}'[Do not activate the repository]' \
      ':REPO: '
  } # }}}

  # $ git dirs active <TAB>
  # <NOTHING>

  function _git-dirs-active _git-dirs-list # {{{
  {
    _git-dirs-_args \
    - '(full)' \
      {-f,--full}'[Display full paths]' \
    - '(relative)' \
      {-r,--relative}'[Display relative paths]' \
    - '(short)' \
      {-s,--short}'[Display basenames]'
  } # }}}

  _git-dirs "$@"

-- 
roman