neogen icon indicating copy to clipboard operation
neogen copied to clipboard

Add `sections` support for generating partial docstrings

Open ColinKennedy opened this issue 1 year ago • 0 comments

closes https://github.com/danymat/neogen/issues/165

This PR adds (Lua API only) support for generating certain sections of a user's docstring. The basic functionality for generator.lua is like this

  • (default behavior) if no sections are given, the user wants to generate the whole docstring

  • if sections are given...

    • we assume that the user wants to add part of a docstring at the current cursor row (and not the usual spot)
    • A given section like "yield" will match all "yield-related" sections
    • any section that is not found is excluded from the docstring output

Extra Notes

Locators Are More Important Now

This PR did expose a slight flaw in the currently supported languages though. Normally Neogen assumes that the user's cursor is directly on the node that they want to generate from. But since this new PR generates docstrings from the cursor position, locators are now more important than they used to be. A couple languages have one already, this PR adds one for Python. Any other language will likely need a locator too.

Until all languages have a locator + unittests, I'm thinking we should fail early if the user provides sections and the given language doesn't provide an explicit locator (it's not in the PR currently but I can add it). What do you think?

Maybe We Should Add at=

The current PR logic assumes that the docstring must generate under the cursor. I think we could expose this behavior as a Lua parameter. The new logic could be

  • If sections is not given, don't generate under the cursor (the current, default behavior)
  • If sections is given and at is not set, assume it is at the user's cursor
  • If at is given, use that cursor location

What do you think?

ColinKennedy avatar Sep 02 '24 06:09 ColinKennedy