neogen/lua/neogen/init.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 = {}
neogen.version = "1.0.0"

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 }
---    }
---   <
---
---@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 = {},
}
--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 Options 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`
---@toc_entry Generate annotations
neogen.generate = function(opts)
    if not conf.enabled then
        notify("Neogen not enabled. Please enable it.", vim.log.levels.WARN)
        return
    end

    require("neogen.generator")(vim.bo.filetype, opts and opts.type)
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?
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

return neogen