leigh/neogen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docgen] Update doc/neogen.txt

Browse Source 
skip-checks: true
This commit is contained in:
github-actions
2022-01-26 12:12:48 +00:00
parent 8a2688914c
commit ffb97ed215
1 changed files with 91 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
doc/neogen.txt
View File

@@ -1,62 +1,65 @@
neogen.txt *neogen* *neogen.nvim* ==============================================================================
------------------------------------------------------------------------------
*neogen*
What is Neogen ?
* NOTE: This file is autogenerated from docs/DOCS.md file # Abstract~
================================================================================
CONTENTS *neogen-contents*
1. Abstract......................................................|neogen-abstract|
2. Concept........................................................|neogen-concept|
3. Usage............................................................|neogen-usage|
4. Basic configurations..............................|neogen-basic_configurations|
5. Advanced configurations........................|neogen-advanced_configurations|
6. Develop........................................................|neogen-develop|
6.1. Developer API......................................|neogen-developer_api|
7. FAQ................................................................|neogen-faq|
================================================================================
ABSTRACT *neogen-abstract*
Neogen is an extensible and extremely configurable annotation generator for your favorite languages Neogen is an extensible and extremely configurable annotation generator for your favorite languages
Want to know what the supported languages are ? Want to know what the supported languages are ?
Check out the up-to-date readme section: https://github.com/danymat/neogen#supported-languages Check out the up-to-date readme section: https://github.com/danymat/neogen#supported-languages
================================================================================ # Concept~
CONCEPT *neogen-concept*
* Create annotations with one keybind, and jump your cursor in the inserted annotation - Create annotations with one keybind, and jump your cursor in the inserted annotation
* Defaults for multiple languages and annotation conventions - Defaults for multiple languages and annotation conventions
* Extremely customizable and extensible - Extremely customizable and extensible
* Written in lua (and uses Tree-sitter) - Written in lua (and uses Tree-sitter)
================================================================================ ------------------------------------------------------------------------------
USAGE *neogen-usage* *neogen.setup()*
`neogen.setup`({opts})
Module setup
Neogen will use tree-sitter parsing to properly generate annotations. 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. 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): For example, if you have a csharp function like (note the cursor position):
> >
public class HelloWorld public class HelloWorld
{ {
public static void Main(string[] args) public static void Main(string[] args)
{ {
# CURSOR HERE # CURSOR HERE
Console.WriteLine("Hello world!"); Console.WriteLine("Hello world!");
return true; return true;
} }
public int someMethod(string str, ref int nm, void* ptr) { return 1; }
} 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: and you call `:Neogen class`, it will generate the annotation for the upper class:
> >
/// <summary> /// <summary>
/// ... /// ...
/// </summary> /// </summary>
public class HelloWorld public class HelloWorld
{ {
< <
Currently supported types are `func`, `class`, `type`, `file`. Currently supported types are `func`, `class`, `type`, `file`.
@@ -65,62 +68,57 @@ To know the supported types for a certain language
NOTE: calling `:Neogen` without any type is the same as `:Neogen func` NOTE: calling `:Neogen` without any type is the same as `:Neogen func`
================================================================================ ------------------------------------------------------------------------------
BASIC CONFIGURATIONS *neogen-basic_configurations* *neogen.configuration*
`neogen.configuration`
# Basic configurations~
Every configuration here is to put inside your `require('neogen').setup {...}` table. Neogen provides those defaults, and you can change them to suit your needs
* `enabled` (defaults: `false`)
Enable Neogen.
* `input_after_comment` (defaults: `true`)
Go to annotation after insertion, and change to insert mode
================================================================================
ADVANCED CONFIGURATIONS *neogen-advanced_configurations*
To customize a language, you can provide a custom table like this:
The defaults are provided here: https://github.com/danymat/neogen/tree/main/lua/neogen/configurations
> >
require('neogen').setup { neogen.configuration = {
languages = { -- Enables Neogen capabilities
csharp = { enabled = true,
-- Configuration here
} -- 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~
* `template.annotation_convention` (default: check the language default configurations) - to configure a language, just add your configurations in the `languages` table
Change the annotation convention to use with the language. For example, for the `lua` lang:
* `template.use_default_comment` (default: `true`) >
Prepend any template line with the default comment for the filetype languages = {
* `template.position` (`fun(node: userdata, type: string):(number,number)?`) lua = { -- Configuration here }
Provide an absolute position for the annotation. }
If return values are `nil`, use default position <
* `template.append`
If you want to customize the position of the annotation
* `template.append.child_name`
What child node to use for appending the annotation
* `template.append.position` (`before/after`)
Relative positioning with `child_name`
* `template.<convention_name>` (replace `<convention_name>` with an annotation convention)
Template for an annotation convention.
To know more about how to create your own template, go here:
https://github.com/danymat/neogen/blob/main/docs/adding-languages.md#default-generator
For example, changing the default annotation convention is as simple as this: - `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
require('neogen').setup {
languages = {
csharp = {
template = { annotation_convention = "..." }
}
}
}
<
================================================================================ ------------------------------------------------------------------------------
DEVELOP *neogen-develop* *test.generator*
`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? * Want to add a new language?
1. Using the defaults to generate a new language support: 1. Using the defaults to generate a new language support:
@@ -131,15 +129,7 @@ DEVELOP *neogen-develo
I guess you can still read the previous links, as they have some valuable knowledge inside. 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. 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 ! free to submit a PR, I will be happy to help you !
--------------------------------------------------------------------------------
DEVELOPER API *neogen-developer_api*
TODO: update doc
================================================================================
FAQ *neogen-faq*
Seems too calm here...
vim:tw=78:ts=8:noet:ft=help:norl: