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
>
require('neogen').setup {
languages = {
csharp = {
-- Configuration here
}
}
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~
* `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
For example, changing the default annotation convention is as simple as this:
>
require('neogen').setup {
- to configure a language, just add your configurations in the `languages` table
For example, for the `lua` lang:
>
languages = {
csharp = {
template = { annotation_convention = "..." }
lua = { -- Configuration here }
}
}
}
<
<
================================================================================
DEVELOP *neogen-develop*
- `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
------------------------------------------------------------------------------
*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?
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: