docs(nvim): add comments and group functions

1 files changed, 70 insertions, 41 deletions

diff --git a/plugin/50-notes.lua b/plugin/50-notes.lua
index 418f49b..de66679 100644
--- a/plugin/50-notes.lua
+++ b/plugin/50-notes.lua
@@ -30,6 +30,10 @@ end
 local notes_dir = vim.fs.normalize(vim.env.NOTES_DIR)
 local tagfile = vim.fs.joinpath(vim.fn.stdpath("state"), "notes-tags")
 
+----------------------------------------------------------------------------------------------------
+-- Tags ---------------------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+
 -- Generates ctags for (markdown) files in `notes_dir`
 local function generate_tags()
 	vim.system({
@@ -43,6 +47,10 @@ local function generate_tags()
 	})
 end
 
+----------------------------------------------------------------------------------------------------
+-- Completion --------------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+
 -- Completion of all `*.md` note names (relative to the notes dir, extension stripped).
 local function note_candidates()
 	local out = {}
@@ -110,31 +118,12 @@ function _G.dotfiles_wikilink_source(findstart, base)
 	return candidates
 end
 
--- Initializes a notes buffer
--- * Include generated notes tags in 'tags' option
--- * Enable wikilink completion
-local function init_notes_buffer()
-	if not vim.tbl_contains(vim.opt_local.tags:get(), tagfile) then
-		vim.opt_local.tags:append(tagfile)
-	end
-	vim.bo.omnifunc = "v:lua.dotfiles_wikilink_source"
-end
+----------------------------------------------------------------------------------------------------
+-- Link rewriting ----------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
 
--- Rewrite `[[oldname]]` / `[[oldname#heading]]` targets to `newname`, matching the target exactly
--- so `[[oldname_extra]]` is left alone. The gsub replacement is a function, so its return value is
--- used literally (no `%` escaping needed).
--- Returns the new text and the number of links rewritten.
-local function rewrite_links(text, oldname, newname)
-	local count = 0
-	local out = text:gsub("%[%[(.-)%]%]", function(inner)
-		local target, rest = inner:match("^([^#]*)(.*)$")
-		if target == oldname then
-			count = count + 1
-			return "[[" .. newname .. rest .. "]]"
-		end
-	end)
-	return out, count
-end
+-- Generic engine: apply a `rewriter(text) -> new_text, n` to notes, editing loaded buffers in place
+-- and the rest on disk. Shared by note rename and section rename below.
 
 -- Rewrite loaded buffer `buf` with `rewriter`
 -- Returns the number of elements rewritten
@@ -212,6 +201,26 @@ local function note_rel_path(path)
 	return (path:sub(#prefix + 1):gsub("%.md$", ""))
 end
 
+----------------------------------------------------------------------------------------------------
+-- Rename note -------------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+
+-- Rewrite `[[oldname]]` / `[[oldname#heading]]` targets to `newname`, matching the target exactly
+-- so `[[oldname_extra]]` is left alone. The gsub replacement is a function, so its return value is
+-- used literally (no `%` escaping needed).
+-- Returns the new text and the number of links rewritten.
+local function rewrite_links(text, oldname, newname)
+	local count = 0
+	local out = text:gsub("%[%[(.-)%]%]", function(inner)
+		local target, rest = inner:match("^([^#]*)(.*)$")
+		if target == oldname then
+			count = count + 1
+			return "[[" .. newname .. rest .. "]]"
+		end
+	end)
+	return out, count
+end
+
 -- Move a file on disk. Returns `true` on success, or `false, err` on failure.
 local function move_file(old_path, new_path)
 	vim.fn.mkdir(vim.fs.dirname(new_path), "p")
@@ -279,6 +288,27 @@ local function rename_current_note(new_path)
 	rename_note(old_path, new_path, buf)
 end
 
+-- `:NotesRename` implementation: take the new note name from the command argument, or prompt for it
+-- (defaulting to the current note's name), then rename via `rename_current_note`.
+local function rename_note_command(opts)
+	if opts.args ~= "" then
+		rename_current_note(opts.args)
+	else
+		vim.ui.input(
+			{ prompt = "Rename note to: ", default = note_rel_path(vim.api.nvim_buf_get_name(0)) },
+			function(input)
+				if input and input ~= "" then
+					rename_current_note(input)
+				end
+			end
+		)
+	end
+end
+
+----------------------------------------------------------------------------------------------------
+-- Rename section ----------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+
 -- Rewrites `[[note#oldhead]]` heading anchors to `newhead` in `text`.
 -- Returns the edited text and the number of substitutions performed.
 local function rewrite_heading_links(text, note, oldhead, newhead)
@@ -349,23 +379,6 @@ local function rename_current_section(new_head)
 	rename_section(note, heading.text, new_head)
 end
 
--- `:NotesRename` implementation: take the new note name from the command argument, or prompt for it
--- (defaulting to the current note's name), then rename via `rename_current_note`.
-local function rename_note_command(opts)
-	if opts.args ~= "" then
-		rename_current_note(opts.args)
-	else
-		vim.ui.input(
-			{ prompt = "Rename note to: ", default = note_rel_path(vim.api.nvim_buf_get_name(0)) },
-			function(input)
-				if input and input ~= "" then
-					rename_current_note(input)
-				end
-			end
-		)
-	end
-end
-
 -- `:NotesRenameSection` implementation: take the new heading from the command argument, or prompt
 -- for it (defaulting to the heading at the cursor), then rename via `rename_current_section`.
 local function rename_section_command(opts)
@@ -384,6 +397,20 @@ local function rename_section_command(opts)
 	end
 end
 
+----------------------------------------------------------------------------------------------------
+-- Buffer init & pickers ---------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+
+-- Initializes a notes buffer
+-- * Include generated notes tags in 'tags' option
+-- * Enable wikilink completion
+local function init_notes_buffer()
+	if not vim.tbl_contains(vim.opt_local.tags:get(), tagfile) then
+		vim.opt_local.tags:append(tagfile)
+	end
+	vim.bo.omnifunc = "v:lua.dotfiles_wikilink_source"
+end
+
 local function find_notes_by_tag()
 	require("fzf-lua").tags({
 		ctags_file = tagfile,
@@ -407,6 +434,8 @@ local function open_notes()
 end
 
 ----------------------------------------------------------------------------------------------------
+-- Setup -------------------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
 
 -- Initializes note buffer
 vim.api.nvim_create_autocmd({ "BufReadPost", "BufNewFile" }, {