Merge branch 'main' into throws-statement-java

README.md

@@ -100,7 +100,7 @@ And this is done via the `snippet_engine` option in neogen's setup:
 
 - `snippet_engine` option will use provided engine to place the annotations:
 
-Currently supported: `luasnip`.
+Currently supported: `luasnip`, `snippy`.
 
 ```lua
 require('neogen').setup({ snippet_engine = "luasnip" })

doc/neogen.txt

@@ -152,6 +152,9 @@ Parameters~
 {opts} `(table)` Optional configs to change default behaviour of generation.
  - {opts.type} `(string, default: "func")` Which type we are trying to use for generating annotations.
    Currently supported: `func`, `class`, `type`, `file`
+ - {opts.annotation_convention} `(table)` convention to use for generating annotations.
+   This is language specific. For example, `generate({ annotation_convention = { python = 'numpydoc' } })`
+   If no convention is specified for a specific language, it'll use the default annotation convention for the language.
  - {opts.return_snippet} `boolean` if true, will return 3 values from the function call.
  This option is useful if you want to get the snippet to use with a unsupported snippet engine
  Below are the returned values:
@@ -180,12 +183,16 @@ Feel free to submit a PR, I will be happy to help you !
 We use semantic versioning ! (https://semver.org)
 Here is the current Neogen version:
 >
-  neogen.version = "2.6.0"
+  neogen.version = "2.8.0"
 <
 # Changelog~
 
 Note: We will only document `major` and `minor` versions, not `patch` ones.
 
+## 2.8.0~
+  - Specify annotation convention on `generate()` method (see |neogen.generate()|)
+## 2.7.0~
+  - Add support for `snippy` snippet engine ! (see |neogen-snippet-integration|)
 ## 2.6.0~
   - Add support for placeholders in snippet insertion !
     None: placeholders are automatically set when using a bundled snippet engine.
@@ -235,6 +242,7 @@ To use a snippet engine, pass the option into neogen setup:
 <
 Some snippet engines come out of the box bundled with neogen:
 - `"luasnip"` (https://github.com/L3MON4D3/LuaSnip)
+- `"snippy"` (https://github.com/dcampos/nvim-snippy)
 
 If you want to customize the placeholders, you can use `placeholders_text` option:
 >
@@ -287,7 +295,7 @@ Class~
 Fields~
 {annotation_convention} `(string)` select which annotation convention to use
 {use_default_comment} `(boolean)` Prepend default filetype comment before a annotation
-{append?} neogen.TemplateConfig.Append custom placement of the annotation
+{append} `(optional)` neogen.TemplateConfig.Append custom placement of the annotation
 {position} `(fun(node: userdata, type: string): number,number)` Provide an absolute position for the annotation
   If values are `nil`, use default positioning
 
@@ -296,7 +304,7 @@ Class~
 {child_name} `(string)` Which child node to use for appending the annotation
 {fallback} `(string)` Node to fallback if `child_name` is not found
 {position} "'after'"|"'before'" Place the annotation relative to position with `child_name` or `fallback`
-{disabled?} `(table)` Disable custom placement for provided types
+{disabled} `(optional)` `(table)` Disable custom placement for provided types
 
 For example, to customize the placement for a python annotation, we can use `append`, like so:
 

lua/neogen/configurations/python.lua

@@ -1,5 +1,5 @@
-local ts_utils = require("nvim-treesitter.ts_utils")
 local nodes_utils = require("neogen.utilities.nodes")
+local helpers = require("neogen.utilities.helpers")
 local extractors = require("neogen.utilities.extractors")
 local locator = require("neogen.locators.default")
 local template = require("neogen.template")
@@ -110,7 +110,7 @@ return {
                             -- Check if function is a static method. If so, will not remove the first parameter
                             if node:parent():type() == "decorated_definition" then
                                 local decorator = nodes_utils:matching_child_nodes(node:parent(), "decorator")
-                                decorator = ts_utils.get_node_text(decorator[1])[1]
+                                decorator = helpers.get_node_text(decorator[1])[1]
                                 if decorator == "@staticmethod" then
                                     remove_identifier = false
                                 end
@@ -129,7 +129,7 @@ return {
                         results[i.Return] = res.return_statement
                         results[i.ReturnTypeHint] = res[i.ReturnTypeHint]
                         results[i.HasReturn] = (res.return_statement or res.anonymous_return or res[i.ReturnTypeHint])
-                                and { true }
+                            and { true }
                             or nil
                         results[i.ArbitraryArgs] = res[i.ArbitraryArgs]
                         results[i.Kwargs] = res[i.Kwargs]
@@ -185,7 +185,7 @@ return {
                         for _, assignment in pairs(nodes["assignment"]) do
                             local left_side = assignment:field("left")[1]
                             local left_attribute = left_side:field("attribute")[1]
-                            left_attribute = ts_utils.get_node_text(left_attribute)[1]
+                            left_attribute = helpers.get_node_text(left_attribute)[1]
                             if left_attribute and not vim.startswith(left_attribute, "_") then
                                 table.insert(results[i.ClassAttribute], left_attribute)
                             end
@@ -233,7 +233,7 @@ return {
                         if child:type() == "comment" then
                             local start_row = child:start()
                             if start_row == 0 then
-                                if vim.startswith(ts_utils.get_node_text(node, 0)[1], "#!") then
+                                if vim.startswith(helpers.get_node_text(node)[1], "#!") then
                                     return 1, 0
                                 end
                             end

lua/neogen/generator.lua

@@ -106,12 +106,14 @@ end
 ---@param data table the data from the granulator, which is a set of [type] = results
 ---@param template table a template from the configuration
 ---@param required_type string
+---@param annotation_convention string
 ---@return table { line, content }, with line being the line to append the content
-local function generate_content(parent, data, template, required_type)
+local function generate_content(parent, data, template, required_type, annotation_convention)
     local row, col = get_place_pos(parent, template.position, template.append, required_type)
 
     local commentstring = vim.trim(vim.bo.commentstring:format(""))
-    local generated_template = template[template.annotation_convention]
+    annotation_convention = annotation_convention or template.annotation_convention
+    local generated_template = template[annotation_convention]
 
     local result = {}
     local default_text = {}
@@ -188,7 +190,7 @@ local function generate_content(parent, data, template, required_type)
 end
 
 return setmetatable({}, {
-    __call = function(_, filetype, typ, return_snippet)
+    __call = function(_, filetype, typ, return_snippet, annotation_convention)
         if filetype == "" then
             notify("No filetype detected", vim.log.levels.WARN)
             return
@@ -204,6 +206,17 @@ return setmetatable({}, {
             notify("Type `" .. typ .. "` not supported", vim.log.levels.WARN)
             return
         end
+        annotation_convention = annotation_convention or {}
+        if annotation_convention[filetype] and not template[annotation_convention[filetype]] then
+            notify(
+                ("Annotation convention %s not supported for language %s"):format(
+                    annotation_convention[filetype],
+                    filetype
+                ),
+                vim.log.levels.WARN
+            )
+            return
+        end
 
         local parent_node = get_parent_node(filetype, typ, language)
         if not parent_node then
@@ -213,7 +226,13 @@ return setmetatable({}, {
         local data = granulator(parent_node, language.data[typ])
 
         -- Will try to generate the documentation from a template and the data found from the granulator
-        local row, template_content, default_text = generate_content(parent_node, data, template, typ)
+        local row, template_content, default_text = generate_content(
+            parent_node,
+            data,
+            template,
+            typ,
+            annotation_convention[filetype]
+        )
 
         local content = {}
         local marks_pos = {}

lua/neogen/granulator.lua

@@ -1,4 +1,3 @@
-local ts_utils = require("nvim-treesitter.ts_utils")
 local helpers = require("neogen.utilities.helpers")
 
 --- Tries to use the configuration to find all required content nodes from the parent node
@@ -27,14 +26,13 @@ return function(parent_node, node_data)
                 end
 
                 if not data.match or child_node:type() == data.match then
-                    if type(data.extract) == "function" then
+                    if not type(data.extract) == "function" then
-                        -- Extract content from it { [type] = { data } }
+                        return
-                        for type, extracted_data in pairs(data.extract(child_node)) do
+                    end
-                            result[type] = extracted_data
+
-                        end
+                    -- Extract content from it { [type] = { data } }
-                    else
+                    for type, extracted_data in pairs(data.extract(child_node)) do
-                        -- if not extract function, get the text from the node (required: data.type)
+                        result[type] = extracted_data
-                        result[data.type] = ts_utils.get_node_text(child_node)
                     end
                 end
             end

lua/neogen/init.lua

@@ -150,6 +150,9 @@ neogen.configuration = {
 ---@param opts table Optional configs to change default behaviour of generation.
 ---  - {opts.type} `(string, default: "func")` Which type we are trying to use for generating annotations.
 ---    Currently supported: `func`, `class`, `type`, `file`
+---  - {opts.annotation_convention} `(table)` convention to use for generating annotations.
+---    This is language specific. For example, `generate({ annotation_convention = { python = 'numpydoc' } })`
+---    If no convention is specified for a specific language, it'll use the default annotation convention for the language.
 ---  - {opts.return_snippet} `boolean` if true, will return 3 values from the function call.
 ---  This option is useful if you want to get the snippet to use with a unsupported snippet engine
 ---  Below are the returned values:
@@ -163,7 +166,8 @@ neogen.generate = function(opts)
         return
     end
 
-    return require("neogen.generator")(vim.bo.filetype, opts and opts.type, opts and opts.return_snippet)
+    opts = opts or {}
+    return require("neogen.generator")(vim.bo.filetype, opts.type, opts.return_snippet, opts.annotation_convention)
 end
 
 -- Expose more API  ============================================================
@@ -237,6 +241,10 @@ end
 ---
 --- Note: We will only document `major` and `minor` versions, not `patch` ones.
 ---
+--- ## 2.8.0~
+---   - Specify annotation convention on `generate()` method (see |neogen.generate()|)
+--- ## 2.7.0~
+---   - Add support for `snippy` snippet engine ! (see |neogen-snippet-integration|)
 --- ## 2.6.0~
 ---   - Add support for placeholders in snippet insertion !
 ---     None: placeholders are automatically set when using a bundled snippet engine.
@@ -272,7 +280,7 @@ end
 ---     with multiple annotation conventions.
 ---@tag neogen-changelog
 ---@toc_entry Changes in neogen plugin
-neogen.version = "2.6.0"
+neogen.version = "2.8.0"
 --minidoc_afterlines_end
 
 return neogen

lua/neogen/snippet.lua

@@ -11,6 +11,7 @@ local conf = require("neogen.config").get()
 --- <
 --- Some snippet engines come out of the box bundled with neogen:
 --- - `"luasnip"` (https://github.com/L3MON4D3/LuaSnip)
+--- - `"snippy"` (https://github.com/dcampos/nvim-snippy)
 ---
 --- If you want to customize the placeholders, you can use `placeholders_text` option:
 --- >
@@ -94,4 +95,20 @@ snippet.engines.luasnip = function(snip, pos)
     )
 end
 
+--- Expand snippet for snippy engine
+---@param snip string the snippet to expand
+---@param pos table a tuple of row, col
+---@private
+snippet.engines.snippy = function (snip, pos)
+    local ok, snippy = pcall(require, "snippy")
+    if not ok then
+        notify("Snippy not found, aborting...", vim.log.levels.ERROR)
+        return
+    end
+    local row, _ = unpack(pos)
+    vim.api.nvim_buf_set_lines(0, row, row, true, {''}) -- snippy will change `row`
+    vim.api.nvim_win_set_cursor(0, {row + 1, 0}) -- `snip` already has indent so we should ignore `col`
+    snippy.expand_snippet({body = snip})
+end
+
 return snippet

lua/neogen/utilities/extractors.lua

@@ -1,4 +1,4 @@
-local ts_utils = require("nvim-treesitter.ts_utils")
+local helpers = require("neogen.utilities.helpers")
 
 return {
     --- Extract the content from each node from data
@@ -14,7 +14,7 @@ return {
                 return node:type()
             end
             local get_text = function(node)
-                return ts_utils.get_node_text(node)[1]
+                return helpers.get_node_text(node)[1]
             end
             if opts.type then
                 result[k] = vim.tbl_map(get_type, v)

lua/neogen/utilities/helpers.lua

@@ -22,4 +22,13 @@ return {
     split = function(s, sep, plain)
         return vim.fn.has("nvim-0.6") == 1 and vim.split(s, sep, { plain = plain }) or vim.split(s, sep, plain)
     end,
+
+    --- Gets the text from the node
+    ---@private
+    ---@param node userdata node to fetch text from
+    ---@param bufnr? number originated buffer number. Defaults to 0
+    ---@return table newline separated list of text
+    get_node_text = function(node, bufnr)
+        return vim.split(vim.treesitter.query.get_node_text(node, bufnr or 0), "\n")
+    end,
 }