Vimdoc refuses to generate helpfile for dict-functions that are not autoload

[cgsdfc]

While vimdoc supports the notation of @dict, which works with one form of dictionary functions, it skips all the functions that are not autoload. For example, while you can use (example taken from maktaba)

""
" @dict Logger
" Interface for a plugin to send log messages to maktaba.

""
" @dict Logger
" Logs a {message} with [args...] at DEBUG level.
function! maktaba#log#Debug(message, ...) dict abort
  call call('s:DoMessage', [s:LEVELS.DEBUG, self._context, a:message] + a:000)
endfunction

to generate something like

                                                              *maktaba.Logger*
Interface for a plugin to send log messages to maktaba.

Logger.Debug({message}, [args...])                            *Logger.Debug()*
  Logs a {message} with [args...] at DEBUG level.

you just can't do the following:

""
" @dict Unhappy
" It doesn't work!

let s:unhappy = {}
""
" @dict Unhappy
function! s:unhappy.WannaCry()
  echo 'Sad though'
endfunction

Nothing shows up in the generated helpfile. It seems that vimdoc considers autoload function to be first class thing and ignores the dict-functions defined with the dot notation (a shortcut), no matter what kind of variable preceding the dot.

I am posting this issue because I am currently working out a plugin that allows to define class in vim in a simpler way (Well, it maybe just a problem of style). My plugin uses the dot notation a lot and if vimdoc doesn't work with that, I will end up with no doc or some messy workaround code. And I hope some support to this style can be patched in vimdoc.

[dbarnett]

Yep, I thought maybe an explicit @public, @dict dict.fn or @function dict.fn might help, but I tried some variations on that and didn't see any existing workaround either. Looks like you'd need to tweak the function_line regex and then change the code that uses it to accommodate the different styles and e.g. make sure it doesn't accidentally start publishing regular script-local functions.

[cgsdfc]

Sorry for late reply but I am glad my issue gains concern finally. Well, I have tried a workaround. Although it is stupid, I'd like to share:

""
" This dummy function is for vimdoc to generate document!
function! file#func(...)
endfunction
delf file#func

Never use it because it not only looks stupid but also brings overhead to Vim for loading this script. Besides, I asked a question for whether an alternative tool like vimdoc exist but as you can see, up till now nobody has answered it, which gives me a hint that I'd better stick with vimdoc. Never mind, I have strong faith with tools coming from google :smile_cat: .

So supposed most of the plugins' authors'd like to write the help by hand, I still believe that an automated tool is helpful as just looking at counterparts of other languages, such as docstrip for TeX, docstr for Python, e.g. What's more, the Vim plugin community already has a nearly full chain of tools:

• We have vader.vim, vroom, vspec .e.g. for testing.
• We have convimerage .e.g. for coverage.
• And a lot of mature schemes for CI.

The list of aspects and tools goes longer. It seems that document tools aren't drawn as much attention as other aspects and the reasons of this phenomenon remain unclear to me. However, why sit back and wait for the trends when I really have a request for features? I think I will start by improving vimdoc as far as I can :smile: .

[dbarnett]

Just checking in, have you gotten any further with making this case work? Are you still interested in contributing a fix?

I agree there's no reason to skip functions that aren't autoload for this, so +1 to making your example case work as described. If fixing the function regex is tricky, you could also leave that alone for now and try making explicit syntax more robust so @dict Dict.Fn writes something whether or not it finds a corresponding function definition.

[cgsdfc]

No really. I am currently busy on school homework project and forgot this issue long ago. I do vimscript mainly for self interest. By the time I post this issue, I was not quite good at Python. Now I get better, but not in the state of contributing something back.

As a side note, I think most of the vim plugins write their own doc or use some other scripts to convert README to the help files. As vimscript is not of industrial strength in terms of speed or general purpose language, the code scales quite poorly and once it scales up, it mostly will be rewritten in other languages. So I think the doc one put in vimscript is mostly for the author's sake. A clear string describing the things will suffice in most cases. So I turn out not relying on such tools.

[dbarnett]

Now you mention it, plugins with most of the logic in python might benefit from some instrumentation to collect doc comments from the python too.

You are correct that most plugin authors write vim helpdoc files by hand if they write them at all. We believe there's value in providing usage info through vim's built-in :help for nontrivial plugins and that vimdoc is a good tool for doing that and keeping it up-to-date without having to learn arcane helpdoc syntax, but we realize the trade-off isn't worth it for everyone.

Anyway, still a good feature request and probably a simple fix for anyone who has some cycles to work on it.