Allow docvim blocks to appear inside function bodies
authorGreg Hurrell <greg@hurrell.net>
Thu, 30 Jul 2015 14:12:14 +0000 (07:12 -0700)
committerGreg Hurrell <greg@hurrell.net>
Thu, 30 Jul 2015 14:12:14 +0000 (07:12 -0700)
commit16e60c384bae2f1cea9da26c4408920464c44117
treee53771ab7526eb42fd66373ac3bdcc33392161ee
parenta587b045652e5a031b235515ce372a0e892ca837
Allow docvim blocks to appear inside function bodies

For example, I just had a case where I had an option defined/used inside
a function:

  function s:foo()
    ""
    " @option g:SomeOption boolean 1
    "
    " This option does some thing.
    let l:dispatch=get(g:, 'SomeOption', 1)

    " [code that uses the option here...]
  endfunction

Note that @option is a bit different from @mapping and @command. The
latter generally will have one authoritative place where they are
defined and where their documentation can logically/obviously go. An
@option on the other hand, may be used in multiple places.

So it may make sense to either just document these elsewhere (like up in
the @plugin area), or get into the habit of making a centralized place
where option default values are defined, so that they can be documented
independently of their usage sites.
after/syntax/vim.vim