docs(NvimClient.API): add docstrings for public API

[smolck]

Just a start for now, probably will want to update the generator to generate the docstrings for the public event EventHandler ...s to fully document everything (and silence the warnings when publishing the package).

[lgtm-com[bot]]

This pull request introduces 1 alert when merging 9220e9ac8ce16dd735fa0f863e3686e85979e69b into a66c3b2917fb32bba767dd7a55c635f75ea45232 - view on LGTM.com

new alerts:

• 1 for Use of default ToString()

[smolck]

Okay so I've added docs (rough draft) for the UI events; turns out the ui.txt docs for the ui events aren't easily available for use, and I'm not sure if it'd even be worth all the extra work to try and get them (see this commit message).

Ultimately the docs are available (in an arguably better place, for navigation at least) via a quick :help ui-events in nvim, so it's not totally necessary to add them, though I guess it could be nice to have? The thing is it sort of adds noise where as a user of the library you quite possibly just want to know how to use the handler(s), and will read up in the actual nvim help docs if you want to know what the events do/mean (and I mean, if you're dealing with all of this to e.g. make a UI, you should probably read/be reading ui.txt anyways).

Thoughts?

[justinmk]

turns out the ui.txt docs for the ui events aren't easily available for use, and I'm not sure if it'd even be worth all the extra work to try and get them (see this commit message).

yeah I wouldn't bother with that; rather, ui.txt itself should be generated from code, then we could expose it in nvim_get_api().

Thoughts?

I'd say wait until/unless nvim_get_api() exposes the ui.txt docs in a structured way.

[smolck]

Okay so some of the rest of the documentation-related warnings, specifically those for certain params not being documented, I'm not quite sure why the docs aren't being generated to fix those. Also, the reason UiTryResize etc. don't have documentation is because they aren't documented in the neovim source.

I don't think any of those things need to block this (and thus a NuGet release); any objections to just going ahead and merging this, putting out a 0.2 nuget release, and then getting the rest of the docs situation sorted out after? Probably starting upstream with adding documentation for the UI events in the source (in ui_events.in.h) and generating ui.txt from that . . .

[justinmk]

🚢 🇮🇹