From ffb97ed215b7a449801f875ba805b0ec6daece21 Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 26 Jan 2022 12:12:48 +0000 Subject: [PATCH] [docgen] Update doc/neogen.txt skip-checks: true --- doc/neogen.txt | 192 +++++++++++++++++++++++-------------------------- 1 file changed, 91 insertions(+), 101 deletions(-) diff --git a/doc/neogen.txt b/doc/neogen.txt index 4e39df0..5053780 100644 --- a/doc/neogen.txt +++ b/doc/neogen.txt @@ -1,62 +1,65 @@ -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 - { - 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; } - } + 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: + > - /// - /// ... - /// - public class HelloWorld - { + /// + /// ... + /// + public class HelloWorld + { < 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` -================================================================================ -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.` (replace `` 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 +- to configure a language, just add your configurations in the `languages` table + For example, for the `lua` lang: + > + languages = { + lua = { -- Configuration here } + } + < -For example, changing the default annotation convention is as simple as this: -> - require('neogen').setup { - languages = { - csharp = { - template = { annotation_convention = "..." } - } - } - } -< +- `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 -================================================================================ -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? 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: \ No newline at end of file