165 lines
4.8 KiB
Plaintext
165 lines
4.8 KiB
Plaintext
*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`
|
|
- `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.
|
|
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:ft=help:norl:
|