Clean up annotations on APIs that can be made public and document the ability to create custom popups

[zivarah]

As noted in #1542, it could be very useful to use Neogit as a platform for building popups and actions for custom subcommands. Clean up some of the documentation around the builder APIs and mention in the docs the possibility of creating custom commands.

[CKolkey]

Not going to lie, this is actually way simpler than I had in mind - in a good way. I had this whole idea about replacing the builder pattern with a completely declarative approach, which would be a lot of work and, as this shows... entirely not needed. Thanks for that :)

Question for you: would making the git.* modules public be useful? Or a subset of them? Or leave it up to the user to get data via vim.system() or whatever they like. Definitely not something for this PR if so. Just wondering how much of the internal infrastructure would be valuable.

Another aspect of this that would be good to show would be how to integrate a custom popup with the status buffer:

• How the selection gets passed into the popup constructor function
• How to trigger a refresh of the status buffer after running an action

I think those are somewhat unsolved by this (which is fine) - but again, might not be a big deal. What do you think?

[zivarah]

Not going to lie, this is actually way simpler than I had in mind - in a good way. I had this whole idea about replacing the builder pattern with a completely declarative approach, which would be a lot of work and, as this shows... entirely not needed. Thanks for that :)

Oh interesting! Yeah, I figured that the existing mechanisms were fine as they are.

Question for you: would making the git.* modules public be useful? Or a subset of them? Or leave it up to the user to get data via vim.system() or whatever they like. Definitely not something for this PR if so. Just wondering how much of the internal infrastructure would be valuable.

It seems that would be fine -- I haven't really used them but from a glance they seem easy enough to use. The documentation is a bit sparse for some of them, but I think that could be fleshed out in the future.

Another aspect of this that would be good to show would be how to integrate a custom popup with the status buffer:

• How the selection gets passed into the popup constructor function
• How to trigger a refresh of the status buffer after running an action

I think those are somewhat unsolved by this (which is fine) - but again, might not be a big deal. What do you think?

I'm less familiar with these -- would you mind tweaking what I have pushed currently to include what you're envisioning for that? Happy to include it!

[CKolkey]

It seems that would be fine -- I haven't really used them but from a glance they seem easy enough to use. The documentation is a bit sparse for some of them, but I think that could be fleshed out in the future.

Heh, yeah, I was learning lua for the most part by working on this in the beginning. Had no idea how to do type annotations (and they weren't nearly as ubiquitous two years ago, iirc). I try to go back over them to add better types/docs or whatever from time to time.

Another aspect of this that would be good to show would be how to integrate a custom popup with the status buffer:

• How the selection gets passed into the popup constructor function
• How to trigger a refresh of the status buffer after running an action

I think those are somewhat unsolved by this (which is fine) - but again, might not be a big deal. What do you think?

I'm less familiar with these -- would you mind tweaking what I have pushed currently to include what you're envisioning for that? Happy to include it!

I think I can make the latter automatic, and add better docs/types for the former.

[CKolkey]

Really appreciate your initiative here - thank you!