neogen/README.md

Neogen - Your Annotation Toolkit

Table Of Contents

• Features
• Requirements
• Installation
• Usage
• Configuration
• Supported Languages
• Adding Languages
• GIFS

Features

• 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)

Requirements

• Install nvim-treesitter

Installation

Use your favorite package manager to install Neogen, e.g:

use { 
    "danymat/neogen", 
    config = function()
        require('neogen').setup {
            enabled = true
        }
    end,
    requires = "nvim-treesitter/nvim-treesitter"
}

Usage

I exposed a function to generate the annotations.

require('neogen').generate()

You can bind it to your keybind of choice, like so:

local opts = { noremap = true, silent = true }
vim.api.nvim_set_keymap("n", "<Leader>nf", ":lua require('neogen').generate()<CR>", opts)

Calling the generate function without any parameters will try to generate annotations for the current function.

You can provide some options for the generate, like so:

require('neogen').generate({
    type = "func" -- the annotation type to generate. Currently supported: func, class, type, file
})

For example, I can add an other keybind to generate class annotations:

local opts = { noremap = true, silent = true }
vim.api.nvim_set_keymap("n", "<Leader>nc", ":lua require('neogen').generate({ type = 'class' })<CR>", opts)

Cycle between annotations

I added support passing cursor positionings in templates. That means you can now cycle your cursor between different parts of the annotation.

To configure it to the keybind of your choice, you can do something like this:

local opts = { noremap = true, silent = true }
vim.api.nvim_set_keymap("n", "<C-n>", ":lua require('neogen').jump_next()<CR>", opts)
vim.api.nvim_set_keymap("n", "<C-p>", ":lua require('neogen').jump_prev()<CR>", opts)

If you want to use a key that's already used for completion purposes, take a look at the code snippet here:

nvim-cmp

local cmp = require('cmp')
local neogen = require('neogen')

local t = function(str)
    return vim.api.nvim_replace_termcodes(str, true, true, true)
end

local check_back_space = function()
    local col = vim.fn.col '.' - 1
    return col == 0 or vim.fn.getline('.'):sub(col, col):match '%s' ~= nil
end

cmp.setup {
    ...

    -- You must set mapping if you want.
    mapping = {
		["<tab>"] = cmp.mapping(function(fallback)
			if neogen.jumpable() then
				vim.fn.feedkeys(t("<cmd>lua require('neogen').jump_next()<CR>"), "")
			else
				fallback()
			end
		end, {
			"i",
			"s",
		}),
		["<S-tab>"] = cmp.mapping(function(fallback)
			if neogen.jumpable(-1) then
				vim.fn.feedkeys(t("<cmd>lua require('neogen').jump_prev()<CR>"), "")
			else
				fallback()
			end
		end, {
			"i",
			"s",
		}),
    },
    ...
}

Configuration

require('neogen').setup {
        enabled = true,             --if you want to disable Neogen
        input_after_comment = true, -- (default: true) automatic jump (with insert mode) on inserted annotation
        -- jump_map = "<C-e>"       -- (DROPPED SUPPORT, see [here](#cycle-between-annotations) !) The keymap in order to jump in the annotation fields (in insert mode)
    }
}

If you're not satisfied with the default configuration for a language, you can change the defaults like this:

require('neogen').setup {
    enabled = true,
	languages = {
	    lua = {
	        template = {
                    annotation_convention = "emmylua" -- for a full list of annotation_conventions, see supported-languages below,
		    ... -- for more template configurations, see the language's configuration file in configurations/{lang}.lua
		}
	    },
	    ...
    }
}

Supported Languages

There is a list of supported languages and fields, with their annotation style

Language	Annotation conventions	Supported fields	Supported annotation types
lua			func, class, type
	Emmylua ("emmylua")	@param, @varargs, @return, @class, @type
	Ldoc ("ldoc")	@param, @varargs, @return, @class, @type
python			func, class, file
	Google docstrings ("google_docstrings")	Args, Attributes, Returns
	Numpydoc ("numpydoc")	Arguments, Attributes, Returns
javascript			func, class, file
	JSDoc ("jsdoc")	@param, @returns, @class, @classdesc, @module
typescript			func, class, file
	JSDoc ("jsdoc")	@param, @returns, @class, @classdesc, @type, @module
c			func, file
	Doxygen ("doxygen")	@param, @return, @brief, @file
cpp			func, file
	Doxygen ("doxygen")	@param, @return, @tparam, @brief, @file
go
	Godoc ("godoc")
java			func, class
	Javadoc ("javadoc")

Adding Languages

1. Using the defaults to generate a new language support: Adding Languages
2. (advanced) Only if the defaults aren't enough, please see here: Advanced Integration

GIFS

Credits

• Binx, for making that gorgeous logo for free!
  • Github
  • Reddit