Use https://github.com/google/vimdoc for helpfile generation

[stellarhoof]

Manually crafting vim helpfiles is cumbersome and hard to maintain, This can lead to outdated helpfiles and inconsistent formatting.

vimdoc, as with all software, is not perfect. Its automation comes at the price of buying into the rigidity of the formatting it provides and it many cases it's not clear how to acomplish something except through trial and error. The documentation is lacking in that respect. In my musings I've found these some things vimdoc does not handle (not exhaustive):

• Automatic generation of mapping documentation
• Validation of settings, commands, ... when using their corresponding directives (@setting(), @command(), ...)
• Interspersing documentation in generated sections. For example, arbitrary blocks of documentation in between commands.

I still think that despite its shortcomings, vimdoc can potentially save precious time to developers of the plugin, thus lowering the barrier to contributions.

Fixes #128

[stellarhoof]

I've got also a fix to #125 ready for pull request that depends on this one.

[jez]

Maybe I’m old school, but what’s the value to auto-generating a help file?

I’m concerned because:

• I’ve seen few projects that do use one,
• it introduces complexity in the form of a build step,
• the current help file and readme seem to suffice.

I see that your main point is that manually creating help files is cumbersome and hard to maintain.

While it may be a new syntax (Vim helpfile vs Markdown), it’s useful to know what helpfiles are strong and weak at to write idiomatic documentation.

With regard to maintenance, my hope is that code review is sufficient to verify that documentation is updated at the same time as the code is changed.

Of course, I’m relatively inactive with this plugin these days. I’d defer to the other maintainers if they think this will be a useful tool going forward. On Sat, Dec 9, 2017 at 7:45 PM Alejandro Hernandez notifications@github.com wrote:

I've got also a fix to #125 https://github.com/parsonsmatt/intero-neovim/issues/125 ready for pull request that depends on this one.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/parsonsmatt/intero-neovim/pull/129#issuecomment-350523067, or mute the thread https://github.com/notifications/unsubscribe-auth/AFSaVBOqonQNZA9JteNMTrV2_hGkVFabks5s-1PbgaJpZM4Q8MMN .

[stellarhoof]

While it may be a new syntax (Vim helpfile vs Markdown), it’s useful to know what helpfiles are strong and weak at to write idiomatic documentation.

I'm not quite sure what you mean here

Requiring to install a dependency to build the helpfile does create a barrier to contribution, and I agree it's simpler to manage it manually. What worries me is that the docs get out of sync, forcing the users to inspect the code as the source of truth. Let's hope code review is indeed sufficient if the maintainers don't decide to use this.

[rdnetto]

I'm ambivalent about this - it looks like it would force us to be more consistent about our documentation, which is good, but it's effectively introducing a new syntax. I also dislike how much noise its adding to the source code, which makes it harder to identify the actual code.

I'm not going to veto this if someone is really keen to see it merged, but my preference would be to just stick with regular helpfiles. If we are going to generate these, then I'd insist on having a check in CI to make sure they remain in sync.

[stellarhoof]

Closing this then. If the maintainers want it back they can reopen