What does an `autocmd User` do?

Question

I switched to vim-plug recently. In the README, there's this snippet for using YouCompleteMe with vim-plug:

" Code to execute when the plugin is loaded on demand
Plug 'Valloric/YouCompleteMe', { 'for': 'cpp' }
autocmd! User YouCompleteMe if !has('vim_starting') | call youcompleteme#Enable() | endif

What's the autocmd for?

According to :h User:

                                                        User
User                            Never executed automatically.  To be used for
                                autocommands that are only executed with
                                ":doautocmd".

So, apparently it's something I should run manually.

The actual configuration I used was:

" YCM command lifted from vim-plug readme
Plug 'Valloric/YouCompleteMe', { 'do': 'python2 ./install.py --clang-completer --gocode-completer --tern-completer', 'for': ['cpp', 'c', 'go', 'sh', 'js', 'vim'] }
autocmd! User YouCompleteMe if !has('vim_starting') | call youcompleteme#Enable() | endif

Now, for any of these filetypes, I don't need to run any command. YCM starts working as it normally used to, before I switched to vim-plug. Running :doautocmd User YouCompleteMe has no visible effect.

For anything else, :doautocmd just throws an error:

Error detected while processing User Auto commands for "YouCompleteMe":
E117: Unknown function: youcompleteme#Enable

So, it seems I can't use it for enabling YCM for other filetypes on-demand.

What's the point of that autocmd, then?

Answer 1

In my understanding, that example creates a User autocommand named YouCompleteMe which will be fired by vim-plug itself, in order to load the plugin on demand. If I'm not mistaken, here's the place where vim-plug will run the custom autocommand:

function! s:lod(names, types, ...)
  for name in a:names
    call s:remove_triggers(name)
    let s:loaded[name] = 1
  endfor
  call s:reorg_rtp()

  for name in a:names
    let rtp = s:rtp(g:plugs[name])
    for dir in a:types
      call s:source(rtp, dir.'/**/*.vim')
    endfor
    if a:0
      if !s:source(rtp, a:1) && !empty(s:glob(rtp, a:2))
        execute 'runtime' a:1
      endif
      call s:source(rtp, a:2)
    endif
    if exists('#User#'.name)
      execute 'doautocmd User' name        <<<< HERE <<<<<
    endif
  endfor
endfunction

Source code: link

So basically, the intended "user" of this autocmd is vim-plug itself.