==============================================================================
------------------------------------------------------------------------------
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: