Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Access docstrings of defs and decls #1166

Open
danr opened this issue Jan 29, 2017 · 9 comments

Comments

Projects
None yet
4 participants
@danr
Copy link
Contributor

commented Jan 29, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Jan 29, 2017

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

@danr

This comment has been minimized.

Copy link
Contributor Author

commented Jan 29, 2017

Yes! See the use cases!

@lenormf

This comment has been minimized.

Copy link
Contributor

commented Jan 29, 2017

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

@danr

This comment has been minimized.

Copy link
Contributor Author

commented Jan 29, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Jan 29, 2017

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

This comment has been minimized.

Copy link
Contributor Author

commented Jan 29, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Jan 29, 2017

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 #1130

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

@mawww

This comment has been minimized.

Copy link
Owner

commented Jan 29, 2017

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

This comment has been minimized.

Copy link
Contributor

commented May 27, 2017

related PR adding missing docstrings to decl in rc files: #1374

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.