{"id":13412960,"url":"https://github.com/danymat/neogen","last_synced_at":"2025-05-14T12:10:24.039Z","repository":{"id":37528288,"uuid":"396478104","full_name":"danymat/neogen","owner":"danymat","description":"A better annotation generator. Supports multiple languages and annotation conventions.","archived":false,"fork":false,"pushed_at":"2025-05-03T17:57:40.000Z","size":5502,"stargazers_count":1481,"open_issues_count":32,"forks_count":64,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-03T18:30:58.612Z","etag":null,"topics":["annotation","comment","lua","neovim","neovim-annotation","neovim-documentation","neovim-lua","neovim-plugin","nvim"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danymat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"danymat"}},"created_at":"2021-08-15T20:03:20.000Z","updated_at":"2025-05-03T17:57:44.000Z","dependencies_parsed_at":"2023-02-10T02:16:21.798Z","dependency_job_id":"645022ea-8777-4e98-b2dd-a0a4992ad9fa","html_url":"https://github.com/danymat/neogen","commit_stats":{"total_commits":491,"total_committers":45,"mean_commits":"10.911111111111111","dds":0.2892057026476579,"last_synced_commit":"e932ba918b56723436b77aa3efb844a11b2851ab"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danymat%2Fneogen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danymat%2Fneogen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danymat%2Fneogen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danymat%2Fneogen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danymat","download_url":"https://codeload.github.com/danymat/neogen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140756,"owners_count":22021219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","comment","lua","neovim","neovim-annotation","neovim-documentation","neovim-lua","neovim-plugin","nvim"],"created_at":"2024-07-30T20:01:31.627Z","updated_at":"2025-05-14T12:10:24.011Z","avatar_url":"https://github.com/danymat.png","language":"Lua","readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/5306901/141127528-ddff21bb-8da3-43da-8efe-9494a4f231d2.png\" width=250\u003e\u003cbr\u003e\n\n# Neogen - Your Annotation Toolkit\n\n[![Neovim](https://img.shields.io/badge/Neovim%200.10.0+-green.svg?style=for-the-badge\u0026logo=neovim)](https://neovim.io)\n[![Lua](https://img.shields.io/badge/Lua-blue.svg?style=for-the-badge\u0026logo=lua)](http://www.lua.org)\n\n\u003c/div\u003e\n\n# Table Of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Supported Languages](#supported-languages)\n- [Adding Languages](#adding-languages)\n- [GIFS](#gifs)\n- [Credits](#credits)\n- [Support](#support)\n\n## Features\n\n- Create annotations with one keybind, and jump your cursor in the inserted annotation\n- Defaults for multiple languages and annotation conventions\n- Extremely customizable and extensible\n- Written in lua (and uses Tree-sitter)\n\n![screen2](https://user-images.githubusercontent.com/5306901/135055065-08def797-e5af-49c9-b530-dd5973045c4e.gif)\n\n## Requirements\n\nHave Tree-sitter parsers installed on your system. For more information, check out the [:treesitter-parsers](https://neovim.io/doc/user/treesitter.html#treesitter-parsers) neovim help page.\n\n## Installation\n\nUse your favorite package manager to install Neogen, e.g:\n\n###  Lazy\n\n```lua\n{ \n    \"danymat/neogen\", \n    config = true,\n    -- Uncomment next line if you want to follow only stable versions\n    -- version = \"*\" \n}\n```\n\n### Packer\n\n```lua\nuse {\n    \"danymat/neogen\",\n    config = function()\n        require('neogen').setup {}\n    end,\n    -- Uncomment next line if you want to follow only stable versions\n    -- tag = \"*\"\n}\n```\n\n## Usage\n\n- If you want to keep it simple, you can use the `:Neogen` command:\n\n```vim\n\" will generate annotation for the function, class or other relevant type you're currently in\n:Neogen\n\" or you can force a certain type of annotation with `:Neogen \u003cTYPE\u003e`\n\" It'll find the next upper node that matches the type `TYPE`\n\" 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.\n:Neogen func|class|type|...\n```\n\n- If you like to use the lua API, I exposed a function to generate the annotations.\n\n```lua\nrequire('neogen').generate()\n```\n\nYou can bind it to your keybind of choice, like so:\n\n```lua\nlocal opts = { noremap = true, silent = true }\nvim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003enf\", \":lua require('neogen').generate()\u003cCR\u003e\", opts)\n```\n\nCalling the `generate` function without any parameters will try to generate annotations for the current function.\n\nYou can provide some options for the generate, like so:\n\n```lua\nrequire('neogen').generate({\n    type = \"func\" -- the annotation type to generate. Currently supported: func, class, type, file\n})\n```\n\nFor example, I can add an other keybind to generate class annotations:\n\n```lua\nlocal opts = { noremap = true, silent = true }\nvim.api.nvim_set_keymap(\"n\", \"\u003cLeader\u003enc\", \":lua require('neogen').generate({ type = 'class' })\u003cCR\u003e\", opts)\n```\n\n### Snippet support\n\nWe added snippet support, and we provide defaults for some snippet engines.\nAnd this is done via the `snippet_engine` option in neogen's setup:\n\n- `snippet_engine` option will use provided engine to place the annotations:\n\nCurrently supported: `luasnip`, `snippy`, `vsnip`, `nvim`, `mini`.\n\n```lua\nrequire('neogen').setup({ snippet_engine = \"luasnip\" })\n```\n\nThat's all ! You can now use your favorite snippet engine to control the annotation, like jumping between placeholders.\n\nOr, if you want to return the snippet as a string (to integrate with other snippet engines, for example),\nyou can do it by using the `return_snippet` option in the `generate` function:\n\n- `return_snippet` option will return the annotations as lsp snippets.\n\n```lua\nlocal snippet, row, col = require('neogen').generate({ snippet_engine = \"luasnip\" })\n```\n\nAnd then pass the snippet to the plugin's snippet expansion function.\n\n### Default cycling support\n\n_Note that this part is only useful if you don't use the snippets integration._\n\nIf you don't want to use a snippet engine with Neogen, you can leverage Neogen's native jumps between placeholders.\nTo map some keys to the cycling feature, you can do like so:\n\n```lua\nlocal opts = { noremap = true, silent = true }\nvim.api.nvim_set_keymap(\"i\", \"\u003cC-l\u003e\", \":lua require('neogen').jump_next\u003cCR\u003e\", opts)\nvim.api.nvim_set_keymap(\"i\", \"\u003cC-h\u003e\", \":lua require('neogen').jump_prev\u003cCR\u003e\", opts)\n```\n\nOr, if you want to use a key that's already used for completion purposes, take a look at the code snippet here:\n\n\u003cdetails\u003e\n   \u003csummary\u003envim-cmp\u003c/summary\u003e\n\n```lua\nlocal cmp = require('cmp')\nlocal neogen = require('neogen')\n\ncmp.setup {\n    ...\n\n    -- You must set mapping if you want.\n    mapping = {\n        [\"\u003ctab\u003e\"] = cmp.mapping(function(fallback)\n            if neogen.jumpable() then\n                neogen.jump_next()\n            else\n                fallback()\n            end\n        end, {\n            \"i\",\n            \"s\",\n        }),\n        [\"\u003cS-tab\u003e\"] = cmp.mapping(function(fallback)\n            if neogen.jumpable(true) then\n                neogen.jump_prev()\n            else\n                fallback()\n            end\n        end, {\n            \"i\",\n            \"s\",\n        }),\n    },\n    ...\n}\n```\n\n  \u003c/details\u003e\n\n## Configuration\n\n```lua\nrequire('neogen').setup {\n    enabled = true,             --if you want to disable Neogen\n    input_after_comment = true, -- (default: true) automatic jump (with insert mode) on inserted annotation\n    -- jump_map = \"\u003cC-e\u003e\"       -- (DROPPED SUPPORT, see [here](#cycle-between-annotations) !) The keymap in order to jump in the annotation fields (in insert mode)\n}\n```\n\nIf you're not satisfied with the default configuration for a language, you can change the defaults like this:\n\n```lua\nrequire('neogen').setup {\n    enabled = true,\n    languages = {\n        lua = {\n            template = {\n                annotation_convention = \"emmylua\" -- for a full list of annotation_conventions, see supported-languages below,\n                ... -- for more template configurations, see the language's configuration file in configurations/{lang}.lua\n                }\n        },\n        ...\n    }\n}\n```\n\nFor example, if you want to quickly add support for new filetypes based around existing ones, you can do like this:\n\n```lua\nrequire('neogen').setup({\n    languages = {\n        ['cpp.doxygen'] = require('neogen.configurations.cpp')\n    }\n})\n```\n\n## Supported Languages\n\nThere is a list of supported languages and fields, with their annotation style\n\n| Languages       | Annotation Conventions                                                                                                                                                                                                                                                           | Supported annotation types      |\n| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |\n| sh              | [Google Style Guide](https://google.github.io/styleguide/shellguide.html) (`\"google_bash\"`)                                                                                                                                                                                      | `func`, `file`                  |\n| c               | [Doxygen](https://www.doxygen.nl/manual/commands.html) (`\"doxygen\"`)                                                                                                                                                                                                             | `func`, `file`, `type`          |\n| cs              | [Xmldoc](https://docs.microsoft.com/fr-fr/dotnet/csharp/language-reference/xmldoc/) (`\"xmldoc\"`) \u003cbr\u003e [Doxygen](https://www.doxygen.nl/manual/commands.html) (`\"doxygen\"`)                                                                                                       | `func`, `file`, `class`         |\n| cpp             | [Doxygen](https://www.doxygen.nl/manual/commands.html) (`\"doxygen\"`)                                                                                                                                                                                                             | `func`, `file`, `class`         |\n| go              | [GoDoc](https://go.dev/blog/godoc) (`\"godoc\"`)                                                                                                                                                                                                                                   | `func`, `type`                  |\n| java            | [Javadoc](https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#documentationcomments) (`\"javadoc`)                                                                                                                                                            | `func`, `class`, `type`         |\n| javascript      | [JSDoc](https://jsdoc.app) (`\"jsdoc\"`)                                                                                                                                                                                                                                           | `func`, `class`, `type`, `file` |\n| javascriptreact | [JSDoc](https://jsdoc.app) (`\"jsdoc\"`)                                                                                                                                                                                                                                           | `func`, `class`, `type`, `file` |\n| julia             | [Julia](https://docs.julialang.org/en/v1/manual/documentation/#Writing-Documentation) (`\"julia\"`)                                                                                                                                                                                                                                            | `func`, `class` |\n| kotlin          | [KDoc](https://kotlinlang.org/docs/kotlin-doc.html) (`\"kdoc\"`)                                                                                                                                                                                                                   | `func`, `class`                 |\n| lua             | [Emmylua](https://emmylua.github.io/) (`\"emmylua\"`)\u003cbr\u003e [Ldoc](https://stevedonovan.github.io/ldoc/manual/doc.md.html) (`\"ldoc\"`)                                                                                                                                                | `func`, `class`, `type`, `file` |\n| php             | [Php-doc](https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html) (`\"phpdoc\"`)                                                                                                                                                                                           | `func`, `type`, `class`         |\n| python          | [Google docstrings](https://google.github.io/styleguide/pyguide.html) (`\"google_docstrings\"`) \u003cbr\u003e [Numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) (`\"numpydoc\"`) \u003cbr\u003e [reST](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html) (`\"reST\"`) | `func`, `class`, `type`, `file` |\n| ruby            | [YARD](https://yardoc.org/index.html) (`\"yard\"`) \u003cbr\u003e [Rdoc](https://github.com/ruby/rdoc) (`\"rdoc\"`) \u003cbr\u003e [Tomdoc](http://tomdoc.org) (`\"tomdoc\"`)                                                                                                                              | `func`, `type`, `class`         |\n| rust            | [RustDoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) (`\"rustdoc\"`) \u003cbr\u003e [Alternative](https://stackoverflow.com/questions/30009650/how-do-you-document-function-arguments) (`\"rust_alternative\"`)                                                                   | `func`, `file`, `class`         |\n| typescript      | [JSDoc](https://jsdoc.app) (`\"jsdoc\"`) \u003cbr\u003e [TSDoc](https://tsdoc.org) (`\"tsdoc\"`)                                                                                                                                                                                               | `func`, `class`, `type`, `file` |\n| typescriptreact | [JSDoc](https://jsdoc.app) (`\"jsdoc\"`) \u003cbr\u003e [TSDoc](https://tsdoc.org) (`\"tsdoc\"`)                                                                                                                                                                                               | `func`, `class`, `type`, `file` |\n| vue             | [JSDoc](https://jsdoc.app) (`\"jsdoc\"`)                                                                                                                                                                                                                                           | `func`, `class`, `type`, `file` |\n\n## Adding Languages\n\n1. Using the defaults to generate a new language support: [Adding Languages](./docs/adding-languages.md)\n2. (advanced) Only if the defaults aren't enough, please see here: [Advanced Integration](./docs/advanced-integration.md)\n\nTip: 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`.\n    \n![Visualization of this repo](./diagram.svg)\n\n## Tests\nRun tests using this command\n\n```sh\nmake test\n```\n\n## GIFS\n\n![screen1](https://user-images.githubusercontent.com/5306901/135055052-6ee6a5e8-3f30-4c41-872e-e624e21a1e98.gif)\n\n![screen3](https://user-images.githubusercontent.com/5306901/135055174-2a9d8b88-7b23-4513-af91-135d885783ec.gif)\n\n![screen4](https://user-images.githubusercontent.com/5306901/135056308-9808c231-b1fd-4c41-80bd-85a08d7286dd.gif)\n\n## Credits\n\n- Binx, for making that gorgeous logo for free!\n  - [Github](https://github.com/Binx-Codes/)\n  - [Reddit](https://www.reddit.com/u/binxatmachine)\n\n## Support\n\nYou 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 💝\n\n- [Donate here](https://github.com/sponsors/danymat)\n","funding_links":["https://github.com/sponsors/danymat"],"categories":["Editing Support","Lua"],"sub_categories":["Comment"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanymat%2Fneogen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanymat%2Fneogen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanymat%2Fneogen/lists"}