Provide mechanism for doc blocks outside vimscript files

[dbarnett]

For some plugins, there's no natural place to put doc comments like @section blocks to control vimdoc output, so we've resorted to a convention of adding empty plugin/doc.vim files purely to contain the doc comments. This is a little unintuitive and adds unnecessary runtime overhead.

We should investigate an alternative mechanism to define doc sections in a separate non-vimscript file.

[dbarnett]

This may be less of an issue once #24 ('main file' requirement) and #25 (extra crawl paths) are resolved.

[xanderman]

We're encouraging the use of addon-info.json, right? Seems to me like that could be a good place for these directives.

[dbarnett]

Yep, adding them into addon-info.json is one option I'm considering. The downsides are they would be non-standard extensions to the spec, this isn't something we'd ever want to access at runtime unlike many of the other fields there, and huge block strings including line breaks might be cumbersome to drop into JSON with the other metadata. Of course, the configuration files could simply point to standalone text files that include section bodies. (Vimdoc is already pulling some standard fields from addon-info.json, BTW.)

We could just have a separate vimdoc.cfg or vimdoc.json file. We could also move many of the other global directives here (e.g., @order, @stylized, @library) without cluttering up addon-info.json.

There is some complexity involved in adding any such alternative mechanism as opposed to just sticking with doc comments as the only option (e.g., it's another location devs have to be aware of, has to be documented, and if we implement vimdoc syntax highlighting we'd have 2 flavors to highlight). I'm definitely willing to consider the possibility that once #24 and #25 are resolved, doc comments are the only mechanism we really need.