242 lines
8.2 KiB
Lua
242 lines
8.2 KiB
Lua
--- Table of contents:
|
|
---@toc
|
|
---@text
|
|
|
|
--- What is Neogen ?
|
|
---
|
|
--- # Abstract~
|
|
---
|
|
--- Neogen is an extensible and extremely configurable annotation generator for your favorite languages
|
|
---
|
|
--- Want to know what the supported languages are ?
|
|
--- Check out the up-to-date readme section: https://github.com/danymat/neogen#supported-languages
|
|
---
|
|
--- # Concept~
|
|
---
|
|
--- - Create annotations with one keybind, and jump your cursor in the inserted annotation
|
|
--- - Defaults for multiple languages and annotation conventions
|
|
--- - Extremely customizable and extensible
|
|
--- - Written in lua (and uses Tree-sitter)
|
|
---@tag neogen
|
|
---@toc_entry Neogen's purpose
|
|
-- Requires ===================================================================
|
|
local neogen = {}
|
|
|
|
local conf
|
|
local config = require("neogen.config")
|
|
local helpers = require("neogen.utilities.helpers")
|
|
local mark = require("neogen.mark")
|
|
local notify = helpers.notify
|
|
|
|
-- Module definition ==========================================================
|
|
|
|
--- Module setup
|
|
---
|
|
---@param opts table Config table (see |neogen.configuration|)
|
|
---
|
|
---@usage `require('neogen').setup({})` (replace `{}` with your `config` table)
|
|
---@toc_entry The setup function
|
|
neogen.setup = function(opts)
|
|
conf = config.setup(neogen.configuration, opts)
|
|
if conf.enabled then
|
|
neogen.generate_command()
|
|
end
|
|
end
|
|
|
|
--- Neogen Usage
|
|
---
|
|
--- Neogen will use Treesitter parsing to properly generate annotations.
|
|
---
|
|
--- The basic idea is that Neogen will generate annotation to the type you're in.
|
|
--- For example, if you have a csharp function like (note the cursor position):
|
|
---
|
|
--- >
|
|
--- public class HelloWorld
|
|
--- {
|
|
--- public static void Main(string[] args)
|
|
--- {
|
|
--- # CURSOR HERE
|
|
--- Console.WriteLine("Hello world!");
|
|
--- return true;
|
|
--- }
|
|
---
|
|
--- public int someMethod(string str, ref int nm, void* ptr) { return 1; }
|
|
---
|
|
--- }
|
|
--- <
|
|
---
|
|
--- and you call `:Neogen class`, it will generate the annotation for the upper class:
|
|
---
|
|
--- >
|
|
--- /// <summary>
|
|
--- /// ...
|
|
--- /// </summary>
|
|
--- public class HelloWorld
|
|
--- {
|
|
--- <
|
|
---
|
|
--- Currently supported types are `func`, `class`, `type`, `file`.
|
|
--- Check out the up-to-date readme section: https://github.com/danymat/neogen#supported-languages
|
|
--- To know the supported types for a certain language
|
|
---
|
|
--- NOTE: calling `:Neogen` without any type is the same as `:Neogen func`
|
|
---@tag neogen-usage
|
|
---@toc_entry Usage
|
|
|
|
--- # Basic configurations~
|
|
---
|
|
--- Neogen provides those defaults, and you can change them to suit your needs
|
|
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
|
|
---@text # Notes~
|
|
---
|
|
--- - to configure a language, just add your configurations in the `languages` table.
|
|
--- For example, for the `lua` lang:
|
|
--- >
|
|
--- languages = {
|
|
--- lua = { -- Configuration here }
|
|
--- }
|
|
--- <
|
|
--- Default configurations for a languages can be found in `lua/neogen/configurations/<your_language>.lua`
|
|
---
|
|
--- - To know which snippet engines are supported, take a look at |snippet-integration|.
|
|
--- Example: `snippet_engine = "luasnip"`
|
|
---
|
|
---@toc_entry Configure the setup
|
|
---@tag neogen-configuration
|
|
neogen.configuration = {
|
|
-- Enables Neogen capabilities
|
|
enabled = true,
|
|
|
|
-- Go to annotation after insertion, and change to insert mode
|
|
input_after_comment = true,
|
|
|
|
-- Configuration for default languages
|
|
languages = {},
|
|
|
|
-- Use a snippet engine to generate annotations.
|
|
snippet_engine = nil,
|
|
}
|
|
--minidoc_afterlines_end
|
|
|
|
-- Basic API ===================================================================
|
|
|
|
--- The only function required to use Neogen.
|
|
---
|
|
--- It'll try to find the first parent that matches a certain type.
|
|
--- For example, if you are inside a function, and called `generate({ type = "func" })`,
|
|
--- Neogen will go until the start of the function and start annotating for you.
|
|
---
|
|
---@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.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:
|
|
--- - 1: (type: `string[]`) the resulting lsp snippet
|
|
--- - 2: (type: `number`) the `row` to insert the annotations
|
|
--- - 3: (type: `number`) the `col` to insert the annotations
|
|
---@toc_entry Generate annotations
|
|
neogen.generate = function(opts)
|
|
if not conf or not conf.enabled then
|
|
notify("Neogen not enabled. Please enable it.", vim.log.levels.WARN)
|
|
return
|
|
end
|
|
|
|
return require("neogen.generator")(vim.bo.filetype, opts and opts.type, opts and opts.return_snippet)
|
|
end
|
|
|
|
-- Expose more API ============================================================
|
|
|
|
-- Expose match_commands for `:Neogen` completion
|
|
neogen.match_commands = helpers.match_commands
|
|
|
|
--- Get a template for a particular filetype
|
|
---@param filetype? string
|
|
---@return neogen.TemplateConfig?
|
|
---@private
|
|
neogen.get_template = function(filetype)
|
|
local template
|
|
local ft_conf = filetype and conf.languages[filetype] or conf.languages[vim.bo.filetype]
|
|
if ft_conf and ft_conf.template then
|
|
template = ft_conf.template
|
|
end
|
|
return template
|
|
end
|
|
|
|
-- Required for use with completion engine =====================================
|
|
|
|
--- Jumps to the next cursor template position
|
|
---@private
|
|
function neogen.jump_next()
|
|
mark:jump()
|
|
end
|
|
|
|
--- Jumps to the next cursor template position
|
|
---@private
|
|
function neogen.jump_prev()
|
|
mark:jump(true)
|
|
end
|
|
|
|
--- Checks if the cursor can jump backwards or forwards
|
|
--- @param reverse number? if `-1` or true, will try to see if can be jumped backwards
|
|
---@private
|
|
function neogen.jumpable(reverse)
|
|
return mark:jumpable(reverse == -1 or reverse == true)
|
|
end
|
|
|
|
-- Command and autocommands ====================================================
|
|
|
|
--- Generates the `:Neogen` command, which calls `neogen.generate()`
|
|
---@private
|
|
function neogen.generate_command()
|
|
vim.cmd([[
|
|
command! -nargs=? -complete=customlist,v:lua.require'neogen'.match_commands -range -bar Neogen lua require("neogen").generate({ type = <q-args>})
|
|
]])
|
|
end
|
|
|
|
--- Contribute to Neogen
|
|
---
|
|
--- * Want to add a new language?
|
|
--- 1. Using the defaults to generate a new language support:
|
|
--- https://github.com/danymat/neogen/blob/main/docs/adding-languages.md
|
|
--- 2. (advanced) Only if the defaults aren't enough, please see here:
|
|
--- https://github.com/danymat/neogen/blob/main/docs/advanced-integration.md
|
|
--- * Want to contribute to an existing language?
|
|
--- I guess you can still read the previous links, as they have some valuable knowledge inside.
|
|
--- You can go and directly open/edit the configuration file relative to the language you want to contribute to.
|
|
---
|
|
--- Feel free to submit a PR, I will be happy to help you !
|
|
---@tag neogen-develop
|
|
---@toc_entry Contributing
|
|
|
|
--- We use semantic versioning ! (https://semver.org)
|
|
--- Here is the current Neogen version:
|
|
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
|
|
---@text # Changelog~
|
|
---
|
|
--- Note: We will only document `major` and `minor` versions, not `patch` ones.
|
|
---
|
|
--- ## 2.3.0~
|
|
--- - Added bundled support with snippet engines !
|
|
--- Check out |snippet-integration| for basic setup
|
|
--- For more information of possible options, check out |neogen.generate()|
|
|
--- ## 2.2.0~
|
|
--- ### Python~
|
|
--- - Add support for `*args` and `**kwargs`
|
|
--- - Fix python return annotations being inconsistent in numpydoc template
|
|
--- ## 2.1.0~
|
|
--- - Add basic support for `kotlin` (`kdoc`).
|
|
--- ## 2.0.0~
|
|
--- - We made the template API private, only for initial template configuration.
|
|
--- If you want to make a change to a template, please see:
|
|
--- |neogen-template-configuration| and |neogen-annotation|
|
|
--- ## 1.0.0~
|
|
--- - Neogen is officially out ! We support 16 languages as of right now,
|
|
--- with multiple annotation conventions.
|
|
---@tag neogen-changelog
|
|
---@toc_entry Changes in neogen plugin
|
|
neogen.version = "2.3.0"
|
|
--minidoc_afterlines_end
|
|
|
|
return neogen
|