docs(NvimClient.API): add docstrings for public API - #15
Conversation
eb726ea to
ccbc026
Compare
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
7eac95e to
9220e9a
Compare
|
This pull request introduces 1 alert when merging 9220e9a into a66c3b2 - view on LGTM.com new alerts:
|
|
Okay so I've added docs (rough draft) for the UI events; turns out the Ultimately the docs are available (in an arguably better place, for navigation at least) via a quick Thoughts? |
| /// // the above handler code will be run. | ||
| /// </code> | ||
| /// </example> | ||
| /// <seealso cref=""{camelCaseName}EventHandler""/> |
There was a problem hiding this comment.
This is just what I came up with relatively spur-of-the-moment for the docs, lmk if/how it can be improved (and assuming this is how we want to do the docs for these EventHandlers).
d88b648 to
b4c0f1c
Compare
I think we'd need to parse the ui.txt help doc if we wanted to get the documentation from there and use it here, and after testing how it'd look with the grid_line event docs, I'm not even convinced it'd be a good idea anyways to use the docs from ui.txt
b4c0f1c to
ccd2660
Compare
yeah I wouldn't bother with that; rather, ui.txt itself should be generated from code, then we could expose it in
I'd say wait until/unless |
| uiEvents.Select(uiEvent => | ||
| { | ||
| var camelCaseName = StringUtil.ConvertToCamelCase(uiEvent.Name, true); | ||
| var camelCaseName = $"{StringUtil.ConvertToCamelCase(uiEvent.Name, true)}Event"; |
There was a problem hiding this comment.
| var camelCaseName = $"{StringUtil.ConvertToCamelCase(uiEvent.Name, true)}Event"; | |
| var camelCaseName = $"{StringUtil.ConvertToCamelCase(uiEvent.Name, true)}UIEvent"; |
or...
| var camelCaseName = $"{StringUtil.ConvertToCamelCase(uiEvent.Name, true)}Event"; | |
| var camelCaseName = $"UI{StringUtil.ConvertToCamelCase(uiEvent.Name, true)}Event"; |
There was a problem hiding this comment.
Note that if I do this I’ll have to modify a few other parts of the code, since this changes the name structure of all the events entirely (from what #11 made them).
I’m fine with doing this if you think it’s a good idea (although there’s something I dislike about all the events having UIEvent at the end of their names, when we could just do api.UIEvents.Put etc. instead), but it’s kinda outside the scope of this PR. Maybe better suited to a follow-up one?
| /// // Now if this event is emitted after attaching the UI, | ||
| /// // the above handler code will be run. |
There was a problem hiding this comment.
maybe move the comment above the handler definition, and...
| /// // Now if this event is emitted after attaching the UI, | |
| /// // the above handler code will be run. | |
| /// // This handler will be executed whenever the event is emitted after attaching the UI. |
There was a problem hiding this comment.
👍 just unresolved this until I move the comment, then I’ll merge.
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
|
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 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 |
|
🚢 🇮🇹 |
2 participants
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).