feat: add option to specify annotation convention (#97)

To know more about this new version, please visit `:h neogen-changelog` !

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/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