Neogen - Your Annotation Toolkit

Features
Requirements
Installation
Usage
Configuration
Supported Languages
Adding Languages
GIFS
Credits
Support

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)

screen2

Requirements

Install nvim-treesitter

Installation

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

Lazy

{ 
    "danymat/neogen", 
    dependencies = "nvim-treesitter/nvim-treesitter", 
    config = true,
    -- Uncomment next line if you want to follow only stable versions
    -- version = "*" 
}

Packer

use {
    "danymat/neogen",
    config = function()
        require('neogen').setup {}
    end,
    requires = "nvim-treesitter/nvim-treesitter",
    -- Uncomment next line if you want to follow only stable versions
    -- tag = "*"
}

Usage

If you want to keep it simple, you can use the :Neogen command:

" will generate annotation for the function, class or other relevant type you're currently in
:Neogen
" or you can force a certain type of annotation with `:Neogen <TYPE>`
" It'll find the next upper node that matches the type `TYPE`
" E.g if you're on a method of a class and do `:Neogen class`, it'll find the class declaration and generate the annotation.
:Neogen func|class|type|...

If you like to use the lua API, 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)

Snippet support

We added snippet support, and we provide defaults for some snippet engines. 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, snippy, vsnip.

require('neogen').setup({ snippet_engine = "luasnip" })

That's all ! You can now use your favorite snippet engine to control the annotation, like jumping between placeholders.

Or, if you want to return the snippet as a string (to integrate with other snippet engines, for example), you can do it by using the return_snippet option in the generate function:

return_snippet option will return the annotations as lsp snippets.

local snippet, row, col = require('neogen').generate({ snippet_engine = "luasnip" })

And then pass the snippet to the plugin's snippet expansion function.

Default cycling support

Note that this part is only useful if you don't use the snippets integration.

If you don't want to use a snippet engine with Neogen, you can leverage Neogen's native jumps between placeholders. To map some keys to the cycling feature, you can do like so:

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

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

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

cmp.setup {
    ...

    -- You must set mapping if you want.
    mapping = {
        ["<tab>"] = cmp.mapping(function(fallback)
            if neogen.jumpable() then
                neogen.jump_next()
            else
                fallback()
            end
        end, {
            "i",
            "s",
        }),
        ["<S-tab>"] = cmp.mapping(function(fallback)
            if neogen.jumpable(true) then
                neogen.jump_prev()
            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
                }
        },
        ...
    }
}

For example, if you want to quickly add support for new filetypes based around existing ones, you can do like this:

require('neogen').setup({
    languages = {
        ['cpp.doxygen'] = require('neogen.configurations.cpp')
    }
})

Supported Languages

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

| Languages | Annotation Conventions | Supported annotation types | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | sh | Google Style Guide ("google_bash") | func, file | | c | Doxygen ("doxygen") | func, file, type | | cs | Xmldoc ("xmldoc") Doxygen ("doxygen") | func, file, class | | cpp | Doxygen ("doxygen") | func, file, class | | go | GoDoc ("godoc") | func, type | | java | Javadoc ("javadoc) | func, class | | javascript | JSDoc ("jsdoc") | func, class, type, file | | javascriptreact | JSDoc ("jsdoc") | func, class, type, file | | kotlin | KDoc ("kdoc") | func, class | | lua | Emmylua ("emmylua") Ldoc ("ldoc") | func, class, type, file | | php | Php-doc ("phpdoc") | func, type, class | | python | Google docstrings ("google_docstrings") Numpydoc ("numpydoc") reST ("reST") | func, class, type, file | | ruby | YARD ("yard") Rdoc ("rdoc") Tomdoc ("tomdoc") | func, type, class | | rust | RustDoc ("rustdoc") Alternative ("rust_alternative") | func, file, class | | typescript | JSDoc ("jsdoc") TSDoc ("tsdoc") | func, class, type, file | | typescriptreact | JSDoc ("jsdoc") TSDoc ("tsdoc") | func, class, type, file | | vue | JSDoc ("jsdoc") | func, class, type, file |

Adding Languages

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

Tip: Take a look at this beatiful diagram, showing a representation of the codebase. You can then take a first understanding of what is under the hood. For more details, you can see :h neogen-develop.

Visualization of this repo

GIFS

screen1

screen3

screen4

Credits

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

Support

You like my plugin and want to express your gratitude 👼 ? You can suppport me by donating the equivalent of my morning coffee (no minimum required). I would really appreciate your support as it can motivate me to continue this journey 💝

Donate here

Tabline

akinsho/bufferline.nvim

crispgm/nvim-tabline

koenverburg/minimal-tabline.nvim

nanozuki/tabby.nvim

noib3/nvim-cokeline

romgrk/barbar.nvim

Status Line

alvarosevilla95/luatab.nvim

b0o/incline.nvim

datwaft/bubbly.nvim

feline-nvim/feline.nvim

konapun/vacuumline.nvim

NTBBloodbath/galaxyline.nvim

nvim-lualine/lualine.nvim

rebelot/heirline.nvim

tamton-aquib/staline.nvim

windwp/windline.nvim

Keybinding

b0o/mapx.nvim

folke/which-key.nvim

mrjones2014/legendary.nvim

simrat39/rust-tools.nvim

LSP

b0o/SchemaStore.nvim

folke/trouble.nvim

jose-elias-alvarez/nvim-lsp-ts-utils

neovim/nvim-lspconfig

nvim-lua/lsp_extensions.nvim

nvim-lua/lsp-status.nvim

ray-x/navigator.lua

williamboman/nvim-lsp-installer

Guides

bennypowers/nvim-regexplainer

nvim-lua/kickstart.nvim

Colorschemes

catppuccin/nvim

dharmx/nvim-colo

ful1e5/onedark.nvim

HUAHUAI23/nvim-quietlight

kvrohit/substrata.nvim

lalitmee/cobalt2.nvim

luisiacc/gruvbox-baby

mhartington/oceanic-next

Mofiqul/adwaita.nvim

Mofiqul/dracula.nvim

mrjones2014/lighthaus.nvim

navarasu/onedark.nvim

NTBBloodbath/doom-one.nvim

rebelot/kanagawa.nvim

rose-pine/neovim

RRethy/nvim-base16

sunjon/Shade.nvim

themercorp/themer.lua

zanglg/nova.nvim

Comment

danymat/neogen

Utility

echasnovski/mini.nvim

hood/popui.nvim

meznaric/conmenu

mrjones2014/dash.nvim

Cursor Line

edluffy/specs.nvim

mg979/vim-visual-multi

Code Runner

FeiyouG/command_center.nvim

Extras

folke/zen-mode.nvim

goolord/alpha-nvim

Start Up

henriquehbr/nvim-startup.lua

lewis6991/impatient.nvim

Session

HUAHUAI23/telescope-session.nvim

Fuzzy Finder

ibhagwan/fzf-lua

nvim-telescope/telescope.nvim

vijaymarupudi/nvim-fzf

Misc