From 7f81df44098a7fef93d6901a06b8312c5b8619d7 Mon Sep 17 00:00:00 2001
From: Santos Gallegos <stsewd@protonmail.com>
Date: Sun, 9 Aug 2020 11:39:51 -0500
Subject: Docs: documentation for modules/submodules

---
 README.md               | 416 ++++++++++++++++++++++-------------
 doc/nvim-treesitter.txt | 571 +++++++++++++++++++++++++++++++++++-------------
 2 files changed, 685 insertions(+), 302 deletions(-)

diff --git a/README.md b/README.md
index 21d6df24b..e616f9895 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,6 @@
-![Linting and style checking](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg?branch=master)
-![Check loading of syntax files](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg)
-
-[Join us on Zulip !](https://nvim-treesitter.zulipchat.com/join/1twnvjqumn0t97p65eragu5o/)
+[![Zulip chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://nvim-treesitter.zulipchat.com/)
+[![Linting and style](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg?branch=master)](https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Linting+and+style+checking%22+branch%3Amaster)
+[![Syntax files](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg)](https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Check+loading+of+syntax+files%22+branch%3Amaster)
 
 # nvim-treesitter
 
@@ -28,7 +27,7 @@ You can install `nvim-treesitter` with your favorite package manager, or using t
 
 ### Using a package manager
 
-Simply add these lines to your `init.vim` :
+If you are using [vim-plug](https://github.com/junegunn/vim-plug), put this in your `init.vim` file:
 
 ```vim
 Plug 'nvim-treesitter/nvim-treesitter'
@@ -53,7 +52,7 @@ provides two command to tackle this issue:
   `TSInstall <tab>` will give you a list of supported languages, or select `all` to install them all.
 - `TSInstallInfo` to know which parser is installed.
 
-Let's say you need parsers for `lua`, this is how you do with these commands:
+Let's say you need parsers for `lua`, this is how you install it:
 
 ```vim
 :TSInstall lua
@@ -78,92 +77,198 @@ And now you should be ready to use every functionality `nvim-treesitter` provide
 ## Setup
 
 All modules are disabled by default,
-so you'll need to activate them by putting this in your `init.vim`:
+so you'll need to activate them by putting this in your `init.vim` file:
 
 ```lua
 lua <<EOF
 require'nvim-treesitter.configs'.setup {
-    highlight = {
-      enable = true,                    -- false will disable the whole extension
-      disable = { "c", "rust" },        -- list of language that will be disabled
-      custom_captures = {               -- mapping of user defined captures to highlight groups
-        -- ["foo.bar"] = "Identifier"   -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
-      },
+  ensure_installed = "all"      -- one of "all", "language", or a list of languages
+  highlight = {
+    enable = true,              -- false will disable the whole extension
+    disable = { "c", "rust" },  -- list of language that will be disabled
+  },
+}
+EOF
+```
+
+Check [`:h nvim-treesitter-modules`](doc/nvim-treesitter.txt)
+for a list of available modules and its options.
+
+# Available Modules
+
+## Highlight
+
+Consistent syntax highlighting.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  highlight = {
+    enable = true,
+    custom_captures = {
+      -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
+      ["foo.bar"] = "Identifier",
     },
-    incremental_selection = {
-      enable = true,
-      disable = { "cpp", "lua" },
-      keymaps = {                       -- mappings for incremental selection (visual mappings)
-        init_selection = "gnn",         -- maps in normal mode to init the node/scope selection
-        node_incremental = "grn",       -- increment to the upper named parent
-        scope_incremental = "grc",      -- increment to the upper scope (as defined in locals.scm)
-        node_decremental = "grm",       -- decrement to the previous node
-      }
+  },
+}
+EOF
+```
+
+## Incremental selection
+
+Incremental selection based on the named nodes from the grammar.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  incremental_selection = {
+    enable = true,
+    keymaps = {
+      init_selection = "gnn",
+      node_incremental = "grn",
+      scope_incremental = "grc",
+      node_decremental = "grm",
     },
-    refactor = {
-      highlight_definitions = {
-        enable = true
-      },
-      highlight_current_scope = {
-        enable = true
+  },
+}
+EOF
+```
+
+## Refactor: highlight definitions
+
+Highlights definition and usages of the current symbol under the cursor.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  refactor = {
+    highlight_definitions = { enable = true },
+  },
+}
+EOF
+```
+
+## Refactor: highlight current scope
+
+Highlights the block from the current scope where the cursor is.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  refactor = {
+    highlight_current_scope = { enable = true },
+  },
+}
+EOF
+```
+
+## Refactor: smart rename
+
+Renames the symbol under the cursor within the current scope (and current file).
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  refactor = {
+    smart_rename = {
+      enable = true,
+      keymaps = {
+        smart_rename = "grr",
       },
-      smart_rename = {
-        enable = true,
-        keymaps = {
-          smart_rename = "grr"          -- mapping to rename reference under cursor
-        }
+    },
+  },
+}
+EOF
+```
+
+## Refactor: navigation
+
+Provides "go to definition" for the symbol under the cursor,
+and lists the definitions from the current file.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  refactor = {
+    navigation = {
+      enable = true,
+      keymaps = {
+        goto_definition = "gnd",
+        list_definitions = "gnD",
       },
-      navigation = {
-        enable = true,
-        keymaps = {
-          goto_definition = "gnd",      -- mapping to go to definition of symbol under cursor
-          list_definitions = "gnD"      -- mapping to list all definitions in current file
-        }
-      }
     },
-    textobjects = { -- syntax-aware textobjects
-    enable = true,
-    disable = {},
-    keymaps = {
-        ["iL"] = { -- you can define your own textobjects directly here
+  },
+}
+EOF
+```
+
+## Text objects: select
+
+Define your own text objects mappings
+similar to `ip` (inner paragraph) and `ap` (a paragraph).
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  textobjects = {
+    select = {
+      enable = true,
+      keymaps = {
+        -- You can use the capture groups defined in textobjects.scm
+        ["af"] = "@function.outer",
+        ["if"] = "@function.inner",
+        ["ac"] = "@class.outer",
+        ["ic"] = "@class.inner",
+
+        -- Or you can define your own textobjects like this
+        ["iF"] = {
           python = "(function_definition) @function",
           cpp = "(function_definition) @function",
           c = "(function_definition) @function",
-          java = "(method_declaration) @function"
+          java = "(method_declaration) @function",
         },
-        -- or you use the queries from supported languages with textobjects.scm
-        ["af"] = "@function.outer",
-        ["if"] = "@function.inner",
-        ["aC"] = "@class.outer",
-        ["iC"] = "@class.inner",
-        ["ac"] = "@conditional.outer",
-        ["ic"] = "@conditional.inner",
-        ["ae"] = "@block.outer",
-        ["ie"] = "@block.inner",
-        ["al"] = "@loop.outer",
-        ["il"] = "@loop.inner",
-        ["is"] = "@statement.inner",
-        ["as"] = "@statement.outer",
-        ["ad"] = "@comment.outer",
-        ["am"] = "@call.outer",
-        ["im"] = "@call.inner"
       },
-      -- swap parameters (keymap -> textobject query)
+    },
+  },
+}
+EOF
+```
+
+## Text objects: swap
+
+Define your own mappings to swap the node under the cursor with the next or previous one,
+like function parameters or arguments.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  textobjects = {
+    swap = {
+      enable = true,
       swap_next = {
-        ["<a-p>"] = "@parameter.inner",
+        ["<leader>a"] = "@parameter.inner",
       },
       swap_previous = {
-        ["<a-P>"] = "@parameter.inner",
-      },
-      -- set mappings to go to start/end of adjacent textobjects (keymap -> textobject query)
-      goto_previous_start = {
-        ["[m"] = "@function.outer",
-        ["[["] = "@class.outer",
-      },
-      goto_previous_end = {
-        ["[M"] = "@function.outer",
-        ["[]"] = "@class.outer",
+        ["<leader>A"] = "@parameter.inner",
       },
+    },
+  },
+}
+EOF
+```
+
+## Text objects: move
+
+Define your own mappings to jump to the next or previous text object.
+This is similar to `]m`, `[m`, `]M`, `[M` Neovim's mappings to jump to the next
+or previous function.
+
+```lua
+lua <<EOF
+require'nvim-treesitter.configs'.setup {
+  textobjects = {
+    move {
+      enable = true,
       goto_next_start = {
         ["]m"] = "@function.outer",
         ["]]"] = "@class.outer",
@@ -172,13 +277,37 @@ require'nvim-treesitter.configs'.setup {
         ["]M"] = "@function.outer",
         ["]["] = "@class.outer",
       },
+      goto_previous_start = {
+        ["[m"] = "@function.outer",
+        ["[["] = "@class.outer",
+      },
+      goto_previous_end = {
+        ["[M"] = "@function.outer",
+        ["[]"] = "@class.outer",
+      },
     },
-    ensure_installed = "all" -- one of "all", "language", or a list of languages
+  },
 }
 EOF
 ```
 
-## Commands
+# Extra features
+
+- Syntax based code folding
+
+```vim
+set foldmethod=expr
+set foldexpr=nvim_treesitter#foldexpr()
+```
+
+- Statusline indicator
+
+```vim
+echo nvim_treesitter#statusline(90)  " 90 can be any length
+module->expression_statement->call->identifier
+```
+
+# Commands
 
 Each feature can be enabled or disabled by different means:
 
@@ -190,33 +319,61 @@ Each feature can be enabled or disabled by different means:
 :TSModuleInfo [{module}] " list information about modules state for each filetype
 ```
 
-## Features and Roadmap
+Check [`:h nvim-treesitter-commands`](doc/nvim-treesitter.txt) for a list of all available commands.
 
-The goal of `nvim-treesitter` is both to provide a simple and easy way to use the interface for Treesitter in Neovim,
-but also to add some functionalities to it:
+# Supported Languages
 
-Some of these features are:
+For `nvim-treesitter` to work, we need to use query files such as those you can find in
+`queries/{lang}/{locals,highlights,textobjects}.scm`
 
-- [x] Incremental selection
-- [x] Syntax based code folding (`set foldmethod=expr foldexpr=nvim_treesitter#foldexpr()`)
-- [x] Consistent syntax highlighting (the api is not quite stable yet)
-- [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
+We are looking for maintainers to write query files for their languages.
 
-You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
-The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
+List of currently supported languages:
 
-## Available Modules
+- [x] bash (maintained by @TravonteD)
+- [x] c (maintained by @vigoux)
+- [x] cpp (maintained by @theHamsta, extends C queries)
+- [x] csharp (maintained by @svermeulen)
+- [x] css (maintained by @TravonteD)
+- [x] dart (maintained by @Akin909)
+- [ ] elm
+- [x] fennel (maintained by @TravonteD)
+- [x] go (maintained by @theHamsta, @WinWisely268)
+- [ ] haskell
+- [x] html (maintained by @TravonteD)
+- [x] java
+- [x] javascript (maintained by @steelsojka)
+- [ ] jsdoc
+- [x] json (maintained by @steelsojka)
+- [ ] julia
+- [x] lua  (maintained by @vigoux)
+- [ ] markdown
+- [ ] nix
+- [ ] ocaml
+- [x] php (maintained by @tk-shirasaka)
+- [x] python (maintained by @theHamsta)
+- [x] regex (maintained by @theHamsta)
+- [x] rst (maintained by @stsewd)
+- [x] ruby (maintained by @TravonteD)
+- [x] rust (partial support, maintained by @vigoux)
+- [ ] scala
+- [ ] swift
+- [x] toml (maintained by @tk-shirasaka)
+- [x] tree-sitter query language (maintained by @steelsojka)
+- [ ] tsx
+- [x] typescript (maintained by @steelsojka)
+- [ ] vue
+- [ ] yaml
+
+# Roadmap
 
-- `highlight`: Consistent syntax highlighting.
-- `incremental_selection`: Syntax based selection.
-- `refactor.highlight_definitions`: Syntax based definition and usage highlighting.
-- `refactor.smart_rename`: Syntax based definition and usage renaming.
-- `refactor.navigation`: Syntax based definition listing and navigation.
-  * List all definitions
-  * Go to definition
-- `textobjects`: Vim textobjects defined by treesitter queries
+The goal of `nvim-treesitter` is both to provide a simple and easy way to use the interface for Treesitter in Neovim,
+but also to add some functionalities to it.
+
+You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
+The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
 
-## Defining Modules
+# Defining Modules
 
 Users and plugin authors can take advantage of modules by creating their own. Modules provide:
 
@@ -227,7 +384,7 @@ Users and plugin authors can take advantage of modules by creating their own. Mo
 You can use the `define_modules` function to define one or more modules or module groups.
 
 ```lua
-require 'nvim-treesitter'.define_modules {
+require'nvim-treesitter'.define_modules {
   my_cool_plugin = {
     attach = function(bufnr, lang)
       -- Do cool stuff here
@@ -251,60 +408,17 @@ Modules can consist of the following properties:
 - `attach`: A function that attaches to a buffer. This is required if `module_path` is not provided.
 - `detach`: A function that detaches from a buffer. This is required if `module_path` is not provided.
 
-## Utils
+# Utils
 
 You can get some utility functions with
 
 ```lua
 local ts_utils = require 'nvim-treesitter.ts_utils'
 ```
-More information is available in the help file (`:help nvim-treesitter-utils`).
-
-## Supported Languages
 
-For `nvim-treesitter` to work, we need to use query files such as those you can find in
-`queries/{lang}/{locals,highlights,textobjects}.scm`
+Check [`:h nvim-treesitter-utils`](doc/nvim-treesitter.txt) for more information.
 
-We are looking for maintainers to write query files for their languages.
-
-List of currently supported languages:
-
-- [x] bash (maintained by @TravonteD)
-- [x] c (maintained by @vigoux)
-- [x] cpp (maintained by @theHamsta, extends C queries)
-- [x] csharp (maintained by @svermeulen)
-- [x] css (maintained by @TravonteD)
-- [x] dart (maintained by @Akin909)
-- [ ] elm
-- [x] fennel (maintained by @TravonteD)
-- [x] go (maintained by @theHamsta, @WinWisely268)
-- [ ] haskell
-- [x] html (maintained by @TravonteD)
-- [x] java
-- [x] javascript (maintained by @steelsojka)
-- [ ] jsdoc
-- [x] json (maintained by @steelsojka)
-- [ ] julia
-- [x] lua  (maintained by @vigoux)
-- [ ] markdown
-- [ ] nix
-- [ ] ocaml
-- [x] php (maintained by @tk-shirasaka)
-- [x] python (maintained by @theHamsta)
-- [x] regex (maintained by @theHamsta)
-- [x] rst (maintained by @stsewd)
-- [x] ruby (maintained by @TravonteD)
-- [x] rust (partial support, maintained by @vigoux)
-- [ ] scala
-- [ ] swift
-- [x] toml (maintained by @tk-shirasaka)
-- [x] tree-sitter query language (maintained by @steelsojka)
-- [ ] tsx
-- [x] typescript (maintained by @steelsojka)
-- [ ] vue
-- [ ] yaml
-
-## User Query Extensions
+# User Query Extensions
 
 Queries are what `nvim-treesitter` uses to extract informations from the syntax tree, and they are
 located in the `queries/{lang}/*` runtime directories (like the `queries` folder of this plugin).
@@ -322,12 +436,12 @@ use is :
 - If you want to override a part of a query (only one match for example), use the `after/queries`
   directory.
 
-## Troubleshooting
+# Troubleshooting
 
 Before doing anything make sure you have the latest version of this plugin and run `:checkhealth nvim_treesitter`.
 This will help you find where the bug might come from.
 
-### Feature `X` does not work for `{language}`...
+## Feature `X` does not work for `{language}`...
 
 First, check the `## {language} parser healthcheck` section of `:checkhealth` if you have any warning.
 If you do, it's highly possible that this is the cause of the problem.
@@ -335,14 +449,22 @@ If everything is okay, then it might be an actual error.
 
 In both cases, feel free to [open an issue here](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose).
 
-### I get `Error detected while processing .../plugin/nvim-treesitter.vim` everytime I open Neovim
+### While typing my code is marked as red
+
+You can deactivate highlighting of syntax errors by adding this to your `init.vim` file:
+
+```vim
+highlight link TSError Normal
+```
+
+## I get `Error detected while processing .../plugin/nvim-treesitter.vim` every time I open Neovim
 
 This is probably due to a change in a parser's grammar or its queries.
 Try updating the parser that you suspect has changed (`:TSUpdate {language}`) or all of them (`:TSUpdate`).
 If the error persists after updating all parsers,
 please [open an issue](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose).
 
-### I experience weird highlighting issues similar to [#78](https://github.com/nvim-treesitter/nvim-treesitter/issues/78)
+## I experience weird highlighting issues similar to [#78](https://github.com/nvim-treesitter/nvim-treesitter/issues/78)
 
 This is a well known issue, which arise when the tree and the buffer are getting out of sync.
 As this issue comes from upstream, we don't have any finite fix. To get around this, you can force reparsing the buffer with this command:
diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt
index 096d8698c..bc70d6d6c 100644
--- a/doc/nvim-treesitter.txt
+++ b/doc/nvim-treesitter.txt
@@ -2,16 +2,21 @@
 
 Minimum version of neovim: nightly
 
-Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>, Vigouroux Thomas <tomvig38@gmail.com>
+Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>
+         Vigouroux Thomas <tomvig38@gmail.com>
+         https://github.com/nvim-treesitter/nvim-treesitter/graphs/contributors
+
+                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-INTRODUCTION					       *nvim-treesitter-intro*
+INTRODUCTION                                           *nvim-treesitter-intro*
 
-nvim-treesitter wraps the neovim treesitter api to provide functionnalities such
-as highlighting and incremental selection, and a command to easily install parsers.
+nvim-treesitter wraps the Neovim treesitter API to provide functionnalities
+such as highlighting and incremental selection, and a command to easily
+install parsers.
 
 ==============================================================================
-QUICK START					  *nvim-treesitter-quickstart*
+QUICK START                                       *nvim-treesitter-quickstart*
 
 Install the parser for your language
 
@@ -25,108 +30,364 @@ To get a list of supported languages
   :TSInstallInfo
 <
 
-By default, everything is disabled. To enable support for features, in your `init.vim`:
+By default, everything is disabled.
+To enable supported features, put this in your `init.vim` file:
 
 >
   lua <<EOF
   require'nvim-treesitter.configs'.setup {
-      highlight = {
-	enable = true,                    -- false will disable the whole extension
-	disable = { "c", "rust" },        -- list of language that will be disabled
-	custom_captures = {               -- mapping of user defined captures to highlight groups
-	  -- ["foo.bar"] = "Identifier"   -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
-	},
-      },
-      incremental_selection = {
-	enable = true,
-	disable = { "cpp", "lua" },
-	keymaps = {                       -- mappings for incremental selection (visual mappings)
-	  init_selection = 'gnn',         -- maps in normal mode to init the node/scope selection
-	  node_incremental = "grn",       -- increment to the upper named parent
-	  scope_incremental = "grc",      -- increment to the upper scope (as defined in locals.scm)
-	  node_decremental = "grm",       -- decrement to the previous node
-	}
-      },
-      refactor = {
-	highlight_definitions = {
-	  enable = true
-	},
-	highlight_current_scope = {
-	  enable = true
-	},
-	smart_rename = {
-	  enable = true,
-	  keymaps = {
-	    smart_rename = "grr"          -- mapping to rename reference under cursor
-	  }
-	},
-	navigation = {
-	  enable = true,
-	  keymaps = {
-	    goto_definition = "gnd",      -- mapping to go to definition of symbol under cursor
-	    list_definitions = "gnD"      -- mapping to list all definitions in current file
-	  }
-	}
+    ensure_installed = "all"      -- one of "all", "language", or a list of languages
+    highlight = {
+      enable = true,              -- false will disable the whole extension
+      disable = { "c", "rust" },  -- list of language that will be disabled
+    },
+  }
+  EOF
+<
+
+See |nvim-treesitter-modules| for a list of all available modules and its options.
+
+==============================================================================
+MODULES                                              *nvim-treesitter-modules*
+
+|nvim-treesitter| provides several functionalities via modules (and submodules),
+each module makes use of the query files defined for each language,
+you can add your own queries too, see |nvim-treesitter-query-extensions|.
+
+All modules are disabled by default, and some provide default keymaps.
+Each module corresponds to an entry in the dictionary passed to the
+`nvim-treesitter.configs.setup` function, this should be in your `init.vim` file.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    -- Modules and its options go here
+    highlight = { enable = true },
+    incremental_selection = { enable = true },
+    refactor = {
+      highlight_definitions = { enable = true },
+      smart_rename = { enable = true },
+      navigation = { enable = true },
+    },
+    textobjects = { enable = true },
+  }
+  EOF
+<
+
+All modules share some common options, like `enable` and `disable`.
+When `enable` is `true` this will enable the module for all supported languages,
+if you want to disable the module for some languages you can pass a list to the `disable` option.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    highlight = {
+      enable = true,
+      disable = { "cpp", "lua" },
+    },
+  }
+  EOF
+<
+
+Options that define or accept a keymap use the same format you use to define
+keymaps in Neovim, so you can write keymaps as  `gd`, `<space>a`, `<leader>a`
+`<C-a>` (control + a), `<A-n>` (alt + n), `<CR>` (enter), etc.
+
+External plugins can provide their own modules with their own options,
+those can also be configured using the `nvim-treesitter.configs.setup`
+function.
+
+------------------------------------------------------------------------------
+HIGHLIGHT                                      *nvim-treesitter-highlight-mod*
+
+Consistent syntax highlighting.
+
+Query files: `highlights.scm`.
+Supported options:
+
+- enable: `true` or `false`.
+- disable: list of languages.
+- custom_captures: A map of user defined capture groups to highlight groups.
+  See |nvim-treesitter-query-extensions|.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    highlight = {
+      enable = true,
+      custom_captures = {
+        -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
+        ["foo.bar"] = "Identifier",
       },
-      textobjects = { -- syntax-aware textobjects
+    },
+  }
+  EOF
+<
+Note: The api is not stable yet.
+
+------------------------------------------------------------------------------
+INCREMENTAL SELECTION              *nvim-treesitter-incremental-selection-mod*
+
+Incremental selection based on the named nodes from the grammar.
+
+Query files: `locals.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- keymaps:
+  - init_selection: in normal mode, start incremental selection.
+    Defaults to `gnn`.
+  - node_incremental: in visual mode, increment to the upper named parent.
+    Defaults to `grn`.
+  - scope_incremental: in visual mode, increment to the upper scope
+    (as defined in `locals.scm`). Defaults to `grc`.
+  - node_decremental: in visual mode, decrement to the previous named node.
+    Defaults to `grm`.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    incremental_selection = {
       enable = true,
-      disable = {},
       keymaps = {
-	  ["iL"] = { -- you can define your own textobjects directly here
-	    python = "(function_definition) @function",
-	    cpp = "(function_definition) @function",
-	    c = "(function_definition) @function",
-	    java = "(method_declaration) @function"
-	  },
-	  -- or you use the queries from supported languages with textobjects.scm
-	  ["af"] = "@function.outer",
-	  ["if"] = "@function.inner",
-	  ["aC"] = "@class.outer",
-	  ["iC"] = "@class.inner",
-	  ["ac"] = "@conditional.outer",
-	  ["ic"] = "@conditional.inner",
-	  ["ae"] = "@block.outer",
-	  ["ie"] = "@block.inner",
-	  ["al"] = "@loop.outer",
-	  ["il"] = "@loop.inner",
-	  ["is"] = "@statement.inner",
-	  ["as"] = "@statement.outer",
-	  ["ad"] = "@comment.outer",
-	  ["am"] = "@call.outer",
-	  ["im"] = "@call.inner"
-	},
-        -- swap parameters (keymap -> textobject query)
-	swap_next = {
-	  ["<a-p>"] = "@parameter.inner",
-	},
-	swap_previous = {
-	  ["<a-P>"] = "@parameter.inner",
-	},
-        -- set mappings to go to start/end of adjacent textobjects (keymap -> textobject query)
-	goto_previous_start = {
-	  ["[m"] = "@function.outer",
-	  ["[["] = "@class.outer",
-	},
-	goto_previous_end = {
-	  ["[M"] = "@function.outer",
-	  ["[]"] = "@class.outer",
-	},
-	goto_next_start = {
-	  ["]m"] = "@function.outer",
-	  ["]]"] = "@class.outer",
-	},
-	goto_next_end = {
-	  ["]M"] = "@function.outer",
-	  ["]["] = "@class.outer",
-	},
+        init_selection = "gnn",
+        node_incremental = "grn",
+        scope_incremental = "grc",
+        node_decremental = "grm",
+      },
+    },
+  }
+  EOF
+<
+
+------------------------------------------------------------------------------
+REFACTOR                                        *nvim-treesitter-refactor-mod*
+
+                                *nvim-treesitter-highlight-definitions-submod*
+Highlight definitions~
+
+Highlights definition and usages of the current symbol under the cursor.
+
+Query files: `locals.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    refactor = {
+      highlight_definitions = { enable = true },
+    },
+  }
+  EOF
+<
+
+                              *nvim-treesitter-highlight-current-scope-submod*
+Highlight current scope~
+
+Highlights the block from the current scope where the cursor is.
+
+Query files: `locals.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    refactor = {
+      highlight_current_scope = { enable = true },
+    },
+  }
+  EOF
+<
+
+                                         *nvim-treesitter-smart-rename-submod*
+Smart rename~
+
+Renames the symbol under the cursor within the current scope (and current file).
+
+Query files: `locals.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- keymaps:
+  - smart_rename: rename symbol under the cursor.
+    Defaults to `grr`.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    refactor = {
+      smart_rename = {
+        enable = true,
+        keymaps = {
+          smart_rename = "grr",
+        },
+      },
+    },
+  }
+  EOF
+<
+
+                                           *nvim-treesitter-navigation-submod*
+Navigation~
+
+Provides "go to definition" for the symbol under the cursor,
+and lists the definitions from the current file.
+
+Query files: `locals.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- keymaps:
+  - goto_definition: go to the definition of the symbol under the cursor.
+    Defaults to `gnd`.
+  - list_definitions: list all definitions from the current file.
+    Defaults to `gnD`.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    refactor = {
+      navigation = {
+        enable = true,
+        keymaps = {
+          goto_definition = "gnd",
+          list_definitions = "gnD",
+        },
+      },
+    },
+  }
+  EOF
+<
+
+------------------------------------------------------------------------------
+TEXT OBJECTS                                 *nvim-treesitter-textobjects-mod*
+
+Syntax aware |text-objects|.
+
+                                  *nvim-treesitter-text-objects-select-submod*
+Text object selection~
+
+Define your own text objects mappings
+similar to `ip` (inner paragraph) and `ap` (a paragraph).
+
+Query files: `textobjects.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- keymaps: map of keymaps to a tree-sitter query
+  (`(function_definition) @function`) or capture group (`@function.inner`).
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    textobjects = {
+      select = {
+        enable = true,
+        keymaps = {
+          -- You can use the capture groups defined in textobjects.scm
+          ["af"] = "@function.outer",
+          ["if"] = "@function.inner",
+          ["ac"] = "@class.outer",
+          ["ic"] = "@class.inner",
+
+          -- Or you can define your own textobjects like this
+          ["iF"] = {
+            python = "(function_definition) @function",
+            cpp = "(function_definition) @function",
+            c = "(function_definition) @function",
+            java = "(method_declaration) @function",
+          },
+        },
+      },
+    },
+  }
+  EOF
+<
+
+                                    *nvim-treesitter-text-objects-swap-submod*
+Swap text objects~
+
+Define your own mappings to swap the node under the cursor with the next or previous one,
+like function parameters or arguments.
+
+Query files: `textobjects.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- swap_next: map of keymaps to a tree-sitter capture group (`@parameter.inner`).
+- swap_previous: same as swap_next.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    textobjects = {
+      swap = {
+        enable = true,
+        swap_next = {
+          ["<leader>a"] = "@parameter.inner",
+        },
+        swap_previous = {
+          ["<leader>A"] = "@parameter.inner",
+        },
+      },
+    },
+  }
+  EOF
+<
+
+                                    *nvim-treesitter-text-objects-move-submod*
+Go to next/previous text object~
+
+Define your own mappings to jump to the next or previous text object.
+This is similar to |]m|, |[m|, |]M|, |[M| Neovim's mappings to jump to the next
+or previous function.
+
+Query files: `textobjects.scm`.
+Supported options:
+- enable: `true` or `false`.
+- disable: list of languages.
+- goto_next_start: map of keymaps to a tree-sitter capture group (`@function.outer`).
+- goto_next_end: same as goto_next_start, but it jumps to the start of
+  the text object.
+- goto_previous_start: same as goto_next_start, but it jumps to the previous
+  text object.
+- goto_previous_end: same as goto_next_end, but it jumps to the previous
+  text object.
+
+>
+  lua <<EOF
+  require'nvim-treesitter.configs'.setup {
+    textobjects = {
+      move {
+        enable = true,
+        goto_next_start = {
+          ["]m"] = "@function.outer",
+          ["]]"] = "@class.outer",
+        },
+        goto_next_end = {
+          ["]M"] = "@function.outer",
+          ["]["] = "@class.outer",
+        },
+        goto_previous_start = {
+          ["[m"] = "@function.outer",
+          ["[["] = "@class.outer",
+        },
+        goto_previous_end = {
+          ["[M"] = "@function.outer",
+          ["[]"] = "@class.outer",
+        },
       },
-      ensure_installed = "all" -- one of "all", "language", or a list of languages
+    },
   }
   EOF
 <
 
 ==============================================================================
-USER QUERY EXTENSIONS			    *nvim-treesitter-query-extensions*
+USER QUERY EXTENSIONS                        *nvim-treesitter-query-extensions*
 
 Queries are what `nvim-treesitter` uses to extract informations from the syntax tree, and they are
 located in the `queries/{lang}/*` runtime directories (like the `queries` folder of this plugin).
@@ -145,44 +406,44 @@ use is :
   directory.
 
 ==============================================================================
-COMMANDS					    *nvim-treesitter-commands*
+COMMANDS                                            *nvim-treesitter-commands*
 
-								  *:TSInstall*
+                                                                  *:TSInstall*
 :TSInstall| {language} ...~
 
 Install one or more treesitter parsers.
 You can use |:TSInstall| `all` to install all parsers.
 
-							      *:TSInstallInfo*
+                                                              *:TSInstallInfo*
 :TSInstallInfo~
 
 List informations about currently installed parsers
 
-							           *:TSUpdate*
+                                                                   *:TSUpdate*
 :TSUpdate {language}~
 
 Update the installed parser of {language} or all installed parsers
 if {language} is omitted.
 
-							        *:TSUninstall*
+                                                                *:TSUninstall*
 :TSUninstall {language}~
 
 Deletes the parser for corresponding {language}. You can use 'all' for
 language to uninstall all parsers.
 
-								*:TSBufEnable*
+                                                                *:TSBufEnable*
 :TSBufEnable {module}~
 
 Enable {module} on the current buffer.
 A list of modules can be found at |:TSModuleInfo|
 
-							       *:TSBufDisable*
+                                                               *:TSBufDisable*
 :TSBufDisable {module}~
 
 Disable {module} on the current buffer
 A list of modules can be found at |:TSModuleInfo|
 
-							     *:TSBufEnableAll*
+                                                             *:TSBufEnableAll*
 :TSBufEnableAll {module} [{language}]~
 
 Enable {module} for the session
@@ -191,7 +452,7 @@ particular language.
 A list of modules can be found at |:TSModuleInfo|
 A list of languages can be found at |:TSInstallInfo|
 
-							    *:TSBufDisableAll*
+                                                            *:TSBufDisableAll*
 :TSBufDisableAll {module} [{language}]~
 
 Disable {module} for the session
@@ -200,42 +461,42 @@ particular language.
 A list of modules can be found at |:TSModuleInfo|
 A list of languages can be found at |:TSInstallInfo|
 
-							       *:TSModuleInfo*
+                                                               *:TSModuleInfo*
 :TSModuleInfo [{module}]~
 
 List modules state for the current session.
 
 ==============================================================================
-UTILS						        *nvim-treesitter-utils*
+UTILS                                                  *nvim-treesitter-utils*
 
 Nvim treesitter has some wrapper functions that you can retrieve with:
 >
     local ts_utils = require 'nvim-treesitter.ts_utils'
 <
 Methods
-						 *ts_utils.get_node_at_cursor*
+                                                 *ts_utils.get_node_at_cursor*
 get_node_at_cursor(winnr)~
 
 `winnr` will be 0 if nil.
 Returns the node under the cursor.
 
-						      *ts_utils.get_node_text*
+                                                      *ts_utils.get_node_text*
 get_node_text(node, bufnr)~
 
 Returns the text content of a `node`.
 
-							  *ts_utils.is_parent*
+                                                          *ts_utils.is_parent*
 is_parent(dest, source)~
 
 Determines whether `dest` is a parent of `source`.
 Returns a boolean.
 
-						 *ts_utils.get_named_children*
+                                                 *ts_utils.get_named_children*
 get_named_children(node)~
 
 Returns a table of named children of `node`.
 
-						      *ts_utilsiget_next_node*
+                                                      *ts_utilsiget_next_node*
 get_next_node(node, allow_switch_parent, allow_next_parent)~
 
 Returns the next node within the same parent.
@@ -245,7 +506,7 @@ when the node is the last node.
 If `allow_next_parent` is true, it will allow next parent if
 the node is the last node and the next parent doesn't have children.
 
-						  *ts_utils.get_previous_node*
+                                                  *ts_utils.get_previous_node*
 get_previous_node(node, allow_switch_parents, allow_prev_parent)~
 
 Returns the previous node within the same parent.
@@ -255,15 +516,15 @@ as |ts_utils.get_next_node| but if the node is the first node.
 ==============================================================================
 FUNCTIONS                                          *nvim-treesitter-functions*
 
-						*nvim_treesitter#statusline()*
+                                                *nvim_treesitter#statusline()*
 nvim_treesitter#statusline(size)~
 
 Returns a string describing the current position in the syntax tree. This
 could be used as a statusline indicator.
-Note: The `size` argument is optionnal. When specified, the string will not be
+Note: The `size` argument is optional. When specified, the string will not be
       longer than `size`.
 
-						  *nvim_treesitter#foldexpr()*
+                                                  *nvim_treesitter#foldexpr()*
 nvim_treesitter#foldexpr()~
 
 Functions to be used to determine the fold level at a given line number.
@@ -279,7 +540,7 @@ Note: This is highly experimental, and folding can break on some types of
 HIGHLIGHTS                                        *nvim-treesitter-highlights*
 
 `TSError`
-								  *hl-TSError*
+                                                                  *hl-TSError*
 For syntax/parser errors.
 
 You can deactivate highlighting of syntax errors by adding this to your
@@ -287,112 +548,112 @@ init.vim: >
   highlight link TSError Normal
 
 `TSPunctDelimiter`
-							 *hl-TSPunctDelimiter*
+                                                         *hl-TSPunctDelimiter*
 For delimiters ie: `.`
 
 `TSPunctBracket`
-							   *hl-TSPunctBracket*
+                                                           *hl-TSPunctBracket*
 For brackets and parens.
 
 `TSPunctSpecial`
-							   *hl-TSPunctSpecial*
+                                                           *hl-TSPunctSpecial*
 For special punctutation that does not fall in the catagories before.
 
 `TSConstant`
-							       *hl-TSConstant*
+                                                               *hl-TSConstant*
 For constants
 
 `TSConstBuiltin`
-							   *hl-TSConstBuiltin*
+                                                           *hl-TSConstBuiltin*
 For constant that are built in the language: `nil` in Lua.
 
 `TSConstMacro`
-							     *hl-TSConstMacro*
+                                                             *hl-TSConstMacro*
 For constants that are defined by macros: `NULL` in C.
 
 `TSString`
-								 *hl-TSString*
+                                                                 *hl-TSString*
 For strings.
 
 `TSStringRegex`
-							    *hl-TSStringRegex*
+                                                            *hl-TSStringRegex*
 For regexes.
 
 `TSStringEscape`
-							   *hl-TSStringEscape*
+                                                           *hl-TSStringEscape*
 For escape characters within a string.
 
 `TSCharacter`
-							      *hl-TSCharacter*
+                                                              *hl-TSCharacter*
 For characters.
 
 `TSNumber`
-								 *hl-TSNumber*
+                                                                 *hl-TSNumber*
 For integers.
 
 `TSBoolean`
-								*hl-TSBoolean*
+                                                                *hl-TSBoolean*
 For booleans.
 
 `TSFloat`
-								  *hl-TSFloat*
+                                                                  *hl-TSFloat*
 For floats.
 
 `TSFunction`
-							       *hl-TSFunction*
+                                                               *hl-TSFunction*
 For function (calls and definitions).
 
 `TSFuncBuiltin`
-							    *hl-TSFuncBuiltin*
+                                                            *hl-TSFuncBuiltin*
 For builtin functions: `table.insert` in Lua.
 
 `TSFuncMacro`
-							      *hl-TSFuncMacro*
+                                                              *hl-TSFuncMacro*
 For macro defined fuctions (calls and definitions): each `macro_rules` in
 Rust.
 
 `TSParameter`
-							      *hl-TSParameter*
+                                                              *hl-TSParameter*
 For parameters of a function.
 
 `TSParameterReference`
-						     *hl-TSParameterReference*
+                                                     *hl-TSParameterReference*
 For references to parameters of a function.
 
 `TSMethod`
-								 *hl-TSMethod*
+                                                                 *hl-TSMethod*
 For method calls and definitions.
 
 `TSField`
-								  *hl-TSField*
+                                                                  *hl-TSField*
 For fields.
 
 `TSProperty`
-							       *hl-TSProperty*
+                                                               *hl-TSProperty*
 Same as `TSField`.
 
 `TSConstructor`
-							    *hl-TSConstructor*
+                                                            *hl-TSConstructor*
 For constructor calls and definitions: `{}` in Lua, and Java constructors.
 
 `TSConditional`
-							    *hl-TSConditional*
+                                                            *hl-TSConditional*
 For keywords related to conditionnals.
 
 `TSRepeat`
-								 *hl-TSRepeat*
+                                                                 *hl-TSRepeat*
 For keywords related to loops.
 
 `TSLabel`
-								  *hl-TSLabel*
+                                                                  *hl-TSLabel*
 For labels: `label:` in C and `:label:` in Lua.
 
 `TSOperator`
-							       *hl-TSOperator*
+                                                               *hl-TSOperator*
 For any operator: `+`, but also `->` and `*` in C.
 
 `TSKeyword`
-								*hl-TSKeyword*
+                                                                *hl-TSKeyword*
 For keywords that don't fall in previous categories.
 
 `TSKeywordFunction`
@@ -400,23 +661,23 @@ For keywords that don't fall in previous categories.
 For keywords used to define a fuction.
 
 `TSException`
-							      *hl-TSException*
+                                                              *hl-TSException*
 For exception related keywords.
 
 `TSType`
-								   *hl-TSType*
+                                                                   *hl-TSType*
 For types.
 
 `TSTypeBuiltin`
-							    *hl-TSTypeBuiltin*
+                                                            *hl-TSTypeBuiltin*
 For builtin types (you guessed it, right ?).
 
 `TSStructure`
-							      *hl-TSStructure*
+                                                              *hl-TSStructure*
 This is left as an exercise for the reader.
 
 `TSInclude`
-								*hl-TSInclude*
+                                                                *hl-TSInclude*
 For includes: `#include` in C, `use` or `extern crate` in Rust, or `require`
 in Lua.
 
@@ -426,32 +687,32 @@ For C++/Dart attributes, annotations that can be attached to the code to
 denote some kind of meta information.
 
 `TSText`
-								   *hl-TSText*
+                                                                   *hl-TSText*
 For strings considered text in a markup language.
 
 `TSStrong`
-								 *hl-TSStrong*
+                                                                 *hl-TSStrong*
 For text to be represented with strong.
 
 `TSEmphasis`
-							       *hl-TSEmphasis*
+                                                               *hl-TSEmphasis*
 For text to be represented with emphasis.
 
 `TSUnderline`
-							      *hl-TSUnderline*
+                                                               *hl-TSUnderline*
 For text to be represented with an underline.
 
 `TSTitle`
-							          *hl-TSTitle*
+                                                                  *hl-TSTitle*
 
 Text that is part of a title.
 
 `TSLiteral`
-								*hl-TSLiteral*
+                                                                *hl-TSLiteral*
 Literal text.
 
 `TSURI`
-								    *hl-TSURI*
+                                                                    *hl-TSURI*
 Any URI like a link or email.
 
 ==============================================================================
@@ -475,4 +736,4 @@ the cursor.
                                                             *hl-TSCurrentScope*
 Used by refactor.highlight_current_scope to highlight the current scope.
 
-vim:tw=78:ts=8:noet:ft=help:norl:
+vim:tw=78:ts=8:expandtab:noet:ft=help:norl:
-- 
cgit v1.2.3-70-g09d2