227 lines
7.7 KiB
Plaintext
227 lines
7.7 KiB
Plaintext
==============================================================================
|
|
------------------------------------------------------------------------------
|
|
Table of contents:
|
|
Neogen's purpose....................................................|neogen|
|
|
The setup function..........................................|neogen.setup()|
|
|
Usage.........................................................|neogen-usage|
|
|
Configure the setup...................................|neogen-configuration|
|
|
Generate annotations.....................................|neogen.generate()|
|
|
Contributing................................................|neogen-develop|
|
|
Customize templates for a language...........|neogen.template_configuration|
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen*
|
|
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)
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen.setup()*
|
|
`neogen.setup`({opts})
|
|
Module setup
|
|
|
|
Parameters~
|
|
{opts} `(table)` Config table (see |neogen.configuration|)
|
|
|
|
Usage~
|
|
`require('neogen').setup({})` (replace `{}` with your `config` table)
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen-usage*
|
|
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`
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen-configuration*
|
|
`neogen.configuration`
|
|
# Basic configurations~
|
|
|
|
Neogen provides those defaults, and you can change them to suit your needs
|
|
>
|
|
neogen.configuration = {
|
|
-- Enables Neogen capabilities
|
|
enabled = true,
|
|
|
|
-- Go to annotation after insertion, and change to insert mode
|
|
input_after_comment = true,
|
|
|
|
-- Symbol to find for jumping cursor in template
|
|
jump_text = "$1",
|
|
|
|
-- Configuration for default languages
|
|
languages = {},
|
|
}
|
|
<
|
|
# Notes~
|
|
|
|
- to configure a language, just add your configurations in the `languages` table
|
|
For example, for the `lua` lang:
|
|
>
|
|
languages = {
|
|
lua = { -- Configuration here }
|
|
}
|
|
<
|
|
|
|
- `jump_text` is widely used and will certainly break most language templates.
|
|
I'm thinking of removing it from defaults so that it can't be modified
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen.generate()*
|
|
`neogen.generate`({opts})
|
|
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.
|
|
|
|
Parameters~
|
|
{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`
|
|
|
|
------------------------------------------------------------------------------
|
|
*neogen-develop*
|
|
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 !
|
|
|
|
|
|
==============================================================================
|
|
------------------------------------------------------------------------------
|
|
*neogen.template_configuration*
|
|
`template_configuration`
|
|
|
|
Each filetype has a template configuration.
|
|
A template configuration is responsible for explicitely adding templates
|
|
corresponding to annotation conventions,
|
|
as well as providing custom configurations in order to be precise about
|
|
how to customize the annotations.
|
|
|
|
Type~
|
|
neogen.TemplateConfig
|
|
|
|
Default values:
|
|
>
|
|
local template_configuration = {
|
|
annotation_convention = nil,
|
|
use_default_comment = false,
|
|
}
|
|
|
|
<
|
|
|
|
------------------------------------------------------------------------------
|
|
# neogen.TemplateConfig~
|
|
|
|
Class~
|
|
{neogen.TemplateConfig} see |template_config|
|
|
Fields~
|
|
{annotation_convention} `(string)` select which annotation convention to use
|
|
{use_default_comment} `(boolean)` Prepend default filetype comment before a annotation
|
|
{append} `(neogen.TemplateConfig.Append|nil)` custom placement of the annotation
|
|
{position} `(fun(node: userdata, type: string): number,number)` Provide an absolute position for the annotation
|
|
If values are `nil`, use default positioning
|
|
|
|
Class~
|
|
{neogen.TemplateConfig.Append}
|
|
{child_name} `(string)` Which child node to use for appending the annotation
|
|
{fallback} `(string)` Node to fallback if `child_name` is not found
|
|
{position} "'after'"|"'before'" Place the annotation relative to position with `child_name` or `fallback`
|
|
{disabled} `(table|nil)` Disable custom placement for provided types
|
|
|
|
For example, to customize the placement for a python annotation, we can use `append`, like so:
|
|
|
|
>
|
|
python = {
|
|
template = {
|
|
append = {
|
|
child_name = "comment", fallback = "block", position = "after"
|
|
}
|
|
}
|
|
}
|
|
<
|
|
|
|
Here, we instruct the generator to place the annotation "after" the "comment" (if not found: "block") node
|
|
|
|
Results in:
|
|
|
|
>
|
|
def test():
|
|
""" """
|
|
pass
|
|
<
|
|
|
|
Or:
|
|
|
|
>
|
|
def test():
|
|
# This is a comment
|
|
""" """
|
|
pass
|
|
<
|
|
|
|
------------------------------------------------------------------------------
|
|
*template_configuration.config()*
|
|
`template_configuration.config`({self}, {tbl})
|
|
template configuration
|
|
Parameters~
|
|
{tbl} neogen.TemplateConfig
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl: |