docs(nvim): edit comments

1 files changed, 11 insertions, 7 deletions

diff --git a/.config/nvim/plugin/10-treesitter.lua b/.config/nvim/plugin/10-treesitter.lua
index 8bb9be1..c0879b6 100644
--- a/.config/nvim/plugin/10-treesitter.lua
+++ b/.config/nvim/plugin/10-treesitter.lua
@@ -1,5 +1,10 @@
 --
--- Treesitter parsers
+-- 10-treesitter.lua
+--
+-- * Installs treesitter parsers.
+-- * Sets up an autocommand to parse the tree synchronously on 'FileType'.
+--   This file should sort early (alphabetically) in plugin/ so that this autcommand triggers before other autcommands
+--   that use the tree.
 --
 
 require("nvim-treesitter").install({
@@ -16,11 +21,10 @@ require("nvim-treesitter").install({
 	"vimdoc",
 })
 
--- Parse the tree as early as possible, which is as soon as we know the filetype
---
--- Event handlers for the same event are triggered in the order they were created. This must be the first FileType
--- handler created so that the tree is parsed for other FileType handlers (which often need the parsed tree). To create
--- it first put this in a file that comes before alphabetically in the `plugin/` directory.
+-- Parse the tree synchronously as early as possible (which is as soon as we know the filetype)
+-- This can be useful for example so that the tree is ready before any other code calls vim.treesitter.get_node(), which
+-- returns nil when the tree is not parsed.
+-- TODO actually test it
 vim.api.nvim_create_autocmd("FileType", {
 	desc = "Start treesitter",
 	group = vim.g.dotfiles.augroup,
@@ -29,7 +33,7 @@ vim.api.nvim_create_autocmd("FileType", {
 		if parser == nil then
 			return
 		end
-		parser:parse() -- Parse once asynchronously; used by logic that needs the parsed tree (like extmarks)
+		parser:parse()
 		vim.treesitter.start()
 	end,
 })