search

google / vimdoc

Helpfile generation for vim
Apache License 2.0
291 stars 28 forks source link

Manual configuration section prevents "maktaba" snippet #78

Open chiphogg opened 9 years ago

chiphogg commented 9 years ago

I'm working on a plugin whose configuration uses a mix of vim builtin settings and maktaba flags. Accordingly, I want to add custom text to the configuration section to point users towards the builtin settings.

However, when I add a custom section like the following, the "this is a maktaba plugin" snippet disappears.

""
" @section Configuration, config
" Mainly uses builtin settings, see |:foo|.

I'm working around this by putting this text in a new section, but it would be great if I could somehow augment instead of replace this snippet.

dbarnett commented 9 years ago

Yeah, that was intentional but not really ideal (and your workaround is the approach I intended to take until we come up with something better).

We need a way to disable/override the default and a way to extend it. Any thoughts on the most natural syntax? One way I can think of would be to add a special placeholder for "default section, if any" that you could explicitly embed in your override. That has parallels in some OOP implementations where you have to explicitly call the parent class's method in your method override if you want it. The downside would be that it's less obvious for people who wanted to extend it instead of overriding (as in your case).

The name @default is already taken. We might be able to make it work for both cases, but we'd be overloading the semantics a little. If we had something like this, we could also use it as a placeholder in other directives like @order so you could say "all the standard sections followed by X, Y, and Z".

chiphogg commented 9 years ago

I thought of the placeholder idea too. It doesn't seem too bad to me.

I'm going to suggest @maktaba_config_snippet, mainly as a concrete name which I want others to improve upon. :)

dbarnett commented 9 years ago

Bob mentioned to me that javadoc uses @inheritDoc for this exact case, so I propose we use that name.

Example:

""
" @section Configuration, config
" @inheritDoc
"
" Mainly uses builtin settings, see |:foo|.
dbarnett commented 9 years ago

Calling @inheritDoc support an enhancement instead of a bug. LMK if you disagree.