==============================================================================
------------------------------------------------------------------------------
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|
  Configurations for the template table........|neogen-template-configuration|
  API to customize templates.............................|neogen-template-api|


------------------------------------------------------------------------------
                                                                        *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.get_template()*
                       `neogen.get_template`({filetype})
Get a template for a particular filetype
Parameters~
{filetype} `(string)`
Return~
`(neogen.TemplateConfig|nil)`

------------------------------------------------------------------------------
                                                                *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*

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.

We exposed some API to help you customize a template, and add your own custom annotations
For this, please go to |neogen.template_api|

Type~
neogen.TemplateConfig

Default values:

>
  local neogen_template = {
      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
<

------------------------------------------------------------------------------
                                                           *neogen-template-api*
# Templates API~

Welcome to the neogen API section for templates.

A template is an entity relative to a filetype that holds configurations for how to place
annotations.
With it, you can add an annotation convention to a filetype, change defaults,
and even provide your own annotation convention !
I exposed some API's, available after you get a template.
Please see |neogen.get_template()| for how to get a template.

Example:
>
 neogen.get_template("python"):config({ annotation_convention = ... })
<

------------------------------------------------------------------------------
                                                  *neogen-template-api.config()*
Updates a template configuration
                         `<template_obj>:config`({tbl})
Parameters~
{tbl} neogen.TemplateConfig Override the template with provided config

------------------------------------------------------------------------------
                                          *neogen-template-api.add_annotation()*
Add an annotation convention to the template
                    `<template_obj>:add_annotation`({name})
Parameters~
{name} `(string)` The name of the annotation convention

------------------------------------------------------------------------------
                                  *neogen-template-api.add_default_annotation()*
Add an annotation convention to the template and make it the default
                `<template_obj>:add_default_annotation`({name})
Parameters~
{name} `(string)` The name of the annotation convention


 vim:tw=78:ts=8:noet:ft=help:norl: