Access docstrings of defs and decls

[danr]

I propose $kak_def_docstrings, and $kak_decl_docstrings to hold all defined defs and decls together with their docstrings.

Use cases:

• Completion and other ways to access the documentation
• Make external documentation for kak "modules"
• If map also had docstrings (#105), and submap info were options (#1165) one could combine this to set the submap info.

[lenormf]

Is there something you would like to use this feature for, precisely?

[danr]

Yes! See the use cases!

[lenormf]

Your usecases are just general ideas of what would be doable, do you need this feature to code something in particular?

[danr]

I think I fail to see the difference.

But perhaps you're asking if lacking this severly blocks my workflow. If so, the answer is no.

[lenormf]

If you're asking for features that we don't need, the incentive to taking the risk of introducing more bugs into the codebase melts away, so I'm asking if you're working on a script that would make use of those features. This is not about the relevancy of the request, but about if we plan on implementing a feature just for the sake of having it.

[danr]

Thank you for your reply.

I hear your concern about bloating the codebase with features we do not need. I share this care about Kakoune. For example: I implemented my own gi and Gi since I thought they were not in the editor because they could be derived.

Regarding this and the other feature requests I raised today I do not think they introduce extra baggage, since:

• I estimate the C++ implementation to be very short (<<50 lines) of simple code. For this one there is some escaping to do, but I expect there to already be routines for that ($kak_selections_desc) that can be reused.

• They introduce substanial improvements and possibilities compared to this low cost. I might not use them today, but when I or someone else has time over, we could build a nice package manager with documentation generation for Kakoune.

Just as you, I have put my confidence in this editor, too. I have spent over 100 hours to configure and think about Kakoune. The issues and feature requests I raise are for the benefit of myself but also for the benefit of all of us. Please, next time you are concerned that I carelessly want to bloat the code base, raise this and state why you estimate the introduced complexity does not outweigh the benefits.

[Delapouite]

While using neovim, I constantly use fzf.vim for this precise purpose : https://github.com/junegunn/fzf.vim

Being able to fuzzy search any list from kakoune in a quick and uniform way really improved my workflow.

In fact one of my last request about searching history is directly related https://github.com/mawww/kakoune/issues/1130

So yes, the more info we can get out of this black box, the better.

[mawww]

I agree that it would be nice to expose the docstrings for a few reasons, mainly allow better integration with external tools providing UI, and the ability to generate documentation from the code.

I am not sure about the interface though, it seems wrong to just put all the infos in a single env var, but on the other hand, using on env var per command might get convoluted to access, as the full var name needs to appear in the %sh{...} block. Also, we use - as a word separator for commands, so we cannot easily use them as part of env var names.

[Delapouite]

related PR adding missing docstrings to decl in rc files: https://github.com/mawww/kakoune/pull/1374

[lenormf]

Related #1605