nvim-ts-context-commentstring.txt

*ts-context-commentstring.txt*

==============================================================================
1. nvim-ts-context-commentstring               *ts-context-commentstring-intro*

*ts-context-commentstring* is a Neovim plugin that uses Treesitter to set the 
'commentstring' option based on the cursor location in a file.

Please see the basic configuration in the `README.md` file. This file only 
includes more advanced documentation.

==============================================================================
2. Supported languages                   *ts-context-commentstring-languages*

Currently, the following languages are supported when they are injected with 
language tree (see `lua/ts_context_commentstring/internal.lua`):

- `astro`
- `bash`
- `c`
- `cpp`
- `css`
- `cue`
- `gleam`
- `glimmer`
- `go`
- `graphql`
- `handlebars`
- `haskell`
- `hcl`
- `html`
- `htmldjango`
- `ini`
- `javascript`
- `kotlin`
- `lua`
- `nix`
- `php`
- `python`
- `rego`
- `rescript`
- `roc`
- `scss`
- `shell`
- `solidity`
- `sql`
- `svelte`
- `terraform`
- `tsx`
- `twig`
- `typescript`
- `vim`
- `vue`
- `zsh`

This means that in any filetype, if the given languages are injected, this 
plugin should detect them and correctly set the 'commentstring'. For example, 
Vue files can be injected with `css` or `javascript`. Even though we don't 
configure anything for Vue explicitly, the 'commentstring' updating logic 
should still work.


==============================================================================
3. Commentstring configuration *ts-context-commentstring-commentstring-configuration*

This plugin initializes using default **plugin** system.

If you need to disable auto-initialization, set
`g:loaded_ts_context_commentstring` to non-zero value.

Custom configuration can be supplied using `setup` function:
>lua
  require('ts_context_commentstring').setup {
    -- ... configuration here
  }
<

Support for more languages can be added quite easily by passing a `languages` (formerly the now deprecated `config`) table
when configuring the plugin:
>lua
  require('ts_context_commentstring').setup {
    languages = {
      css = '// %s',
    },
  }
<

Additionally, some languages are not injected with language tree, but have 
multiple commenting styles in the same language. One such example is 
JavaScript with JSX. The JSX section is not an injected language, but a part 
of the tree generated by the `javascript` Treesitter parser.

In this more complex case, this plugin supports adding queries for specific 
Treesitter nodes. Each node can have its own unique commenting style. For 
example, here's how the default configuration for `javascript` would look 
like:
>lua
  require('ts_context_commentstring').setup {
    languages = {
      javascript = {
        __default = '// %s',
        jsx_element = '{/* %s */}',
        jsx_fragment = '{/* %s */}',
        jsx_attribute = '// %s',
        comment = '// %s',
      },
    },
  }
<

The `__default` value is used when none of the other node types are seen. The 
rest of the keys refer to the type of the Treesitter node. In this example, if 
your cursor is inside a `jsx_element`, then the `{/* %s */}` 'commentstring' 
will be set.

Note that the language refers to the |treesitter| language, not the filetype 
or the file extension.

Additionally, it is possible to have each 'commentstring' configuration be a 
table with custom keys. This can be used to configure separate single and 
multi-line comment styles (useful when integrating with a commenting plugin):
>lua
  require('ts_context_commentstring').setup {
    languages = {
      typescript = { __default = '// %s', __multiline = '/* %s */' },
    },
  }
<

Then, the custom key can be passed to `update_commentstring`:
>lua
  require('ts_context_commentstring').update_commentstring {
    key = '__multiline',
  }
<

Finally, it is possible to customize the tree traversal start location when 
calling `update_commentstring`, this is useful in commenting plugin 
integrations. There are some useful helper functions exported from 
`ts_context_commentstring.utils`:
>lua
  require('ts_context_commentstring').calculate_commentstring {
    location = require('ts_context_commentstring.utils').get_cursor_location(),
  }
<

If you want to calculate your own 'commentstring' you are able to do so with
the `custom_calculation` option:
>lua
  require('ts_context_commentstring').setup {
    custom_calculation = function(node, language_tree)
      -- ...
    end,
  }
<

This is a function that takes in the current node and the language tree which
could be used for context like figuring out which language you should use a 
'commentstring' for. You can also for example figure out which type the current
node is. You need to return a 'commentstring' in the `custom_calculation` if you 
want it to be set.

The `not_nested_languages` table allows you to halt the search for nested
languages at a specified language. This functionality proves beneficial,
for instance, in scenarios such as HTML with Django, where you may want
to include Django comments while excluding HTML content.

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