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

158
doc/neogen.txt
View File

@@ -1,42 +1,42 @@
neogen.txt *neogen* *neogen.nvim*
==============================================================================
------------------------------------------------------------------------------
*neogen*
What is Neogen ?
* NOTE: This file is autogenerated from docs/DOCS.md file
================================================================================
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*
# 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 *neogen-concept*
# 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)
- 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)
================================================================================
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.
For example, if you have a csharp function like (note the cursor position):
>
public class HelloWorld
{
@@ -46,11 +46,14 @@ For example, if you have a csharp function like (note the cursor position):
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>
/// ...
@@ -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`
================================================================================
BASIC CONFIGURATIONS *neogen-basic_configurations*
------------------------------------------------------------------------------
*neogen.configuration*
`neogen.configuration`
# Basic configurations~
Every configuration here is to put inside your `require('neogen').setup {...}` table.
* `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
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:
>
require('neogen').setup {
languages = {
csharp = {
-- Configuration here
}
}
lua = { -- Configuration here }
}
<
* `template.annotation_convention` (default: check the language default configurations)
Change the annotation convention to use with the language.
* `template.use_default_comment` (default: `true`)
Prepend any template line with the default comment for the filetype
* `template.position` (`fun(node: userdata, type: string):(number,number)?`)
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
- `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
For example, changing the default annotation convention is as simple as this:
>
require('neogen').setup {
languages = {
csharp = {
template = { annotation_convention = "..." }
}
}
}
<
------------------------------------------------------------------------------
*test.generator*
`neogen.generate`({opts})
The only function required to use Neogen.
================================================================================
DEVELOP *neogen-develop*
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:
@@ -131,15 +129,7 @@ DEVELOP *neogen-develo
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 !
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: