chore(build): auto-generate vimdoc

doc/harpoonline.txt

@@ -1,4 +1,4 @@
-*harpoonline.txt*        For Neovim >= 0.9.0        Last change: 2024 March 20
+*harpoonline.txt*        For Neovim >= 0.9.0        Last change: 2024 March 21
 
 ==============================================================================
 Table of Contents                              *harpoonline-table-of-contents*
@@ -34,9 +34,9 @@ TOC                                              *harpoonline-harpoonline-toc*
         - |harpoonline-using-mini.deps-and-mini.statusline|
     - |harpoonline-configuration|
         - |harpoonline-formatters|
-            - |harpoonline-the-"short"-builtin|
             - |harpoonline-the-"extended"-builtin|
-            - |harpoonline-modify-a-builtin|
+            - |harpoonline-the-"short"-builtin|
+            - |harpoonline-customize-a-builtin|
             - |harpoonline-use-a-custom-formatter|
     - |harpoonline-harpoon-lists|
     - |harpoonline-recipes|
@@ -96,7 +96,7 @@ USING LAZY.NVIM AND LUALINE ~
         "nvim-lualine/lualine.nvim",
         dependencies =  { "abeldekat/harpoonline", version = "*" },
         config = function()
-          local Harpoonline = require("harpoonline").setup() -- using default config
+          local Harpoonline = require("harpoonline").setup() -- using defaults
           local lualine_c = { Harpoonline.format, "filename" }
           require("lualine").setup({ sections = { lualine_c = lualine_c } })
         end,
@@ -159,18 +159,18 @@ The following configuration is implied when calling `setup` without arguments:
     ---@class HarpoonLineConfig
     Harpoonline.config = {
       ---@type string|nil
-      icon = '󰀱',
+      icon = '󰀱', -- Disable with empty string
 
-      -- Harpoon:list() retrieves the default list: The name of the list is nil.
-      -- The name to display can be configured by using default_list_name
+      -- Harpoon:list() retrieves the default list: The name of that list is nil.
+      -- default_list_name: Configures the display name for the default list.
       ---@type string
       default_list_name = '',
 
       ---@type string
-      formatter = 'extended', -- use a builtin formatter
+      formatter = 'extended', -- short -- use a builtin formatter
 
       ---@type fun():string|nil
-      custom_formatter = nil, -- use this formatter when supplied
+      custom_formatter = nil, -- use this formatter when configured
       ---@type fun()|nil
       on_update = nil, -- optional action to perform after update
     }
@@ -187,63 +187,83 @@ Scenario’s:
 - B: 3 marks, the current buffer is harpooned on mark 2
 
 
-THE “SHORT” BUILTIN
+THE “EXTENDED” BUILTIN
+
+This is the default formatter.
 
 >lua
-    Harpoonline.config = {
-      formatter = 'short',
+    ---@class HarpoonlineBuiltinOptionsExtended
+    H.builtin_options_extended = {
+
+      -- An indicator corresponds to a position in the harpoon list
+      indicators = { '1', '2', '3', '4' },
+      active_indicators = { '[1]', '[2]', '[3]', '[4]' },
+      separator = ' ', -- how to separate the indicators
+
+      -- 1 More indicators than items in the harpoon list:
+      empty_slot = '·', -- a middledot. Disable with empty string
+
+      -- 2 Less indicators than items in the harpoon list
+      more_marks_indicator = '…', -- a horizontal elipsis. Disable with empty string
+      more_marks_active_indicator = '[…]', -- Disable with empty string
     }
 <
 
-Output A: :anchor: `[3]`
-
-Output B: :anchor: `[2|3]`
+Output A: :anchor: `1 2 3 ·`
 
+Output B: :anchor: `1 [2] 3 ·`
 
-THE “EXTENDED” BUILTIN
 
-The default
+THE “SHORT” BUILTIN
 
-Output A: :anchor: `1 2 3 -`
+Add to the config: `{ formatter = 'short'}`
 
-Output B: :anchor: `1 [2] 3 -`
+>lua
+    ---@class HarpoonlineBuiltinOptionsShort
+    H.builtin_options_short = {
+      inner_separator = '|',
+    }
+<
 
+Output A: :anchor: `[3]`
 
-MODIFY A BUILTIN
+Output B: :anchor: `[2|3]`
 
-Builtin formatters: `Harpoonline.formatters` The corresponding formatter
-specific options: `Harpoonline.formatter_opts`
 
-Modify "extended":
+CUSTOMIZE A BUILTIN
 
 >lua
     local Harpoonline = require("harpoonline")
+    ---@type HarpoonlineBuiltinOptionsExtended
+    local opts = {
+      indicators = { "j", "k", "l", "h" },
+      active_indicators = { "<j>", "<k>", "<l>", "<h>" },
+      empty_slot = "", -- disabled
+    }
     Harpoonline.setup({
-      custom_formatter = Harpoonline.gen_override("extended", {
-        indicators = { "j", "k", "l", "h" },
-        active_indicators = { "J", "K", "L", "H" },
-      }),
+      custom_formatter = Harpoonline.gen_override("extended", opts),
     })
 <
 
-Output A: :anchor: `j k l -`
+Output A: :anchor: `j k l`
 
-Output B: :anchor: `j K l -`
+Output B: :anchor: `j <k> l`
 
 
 USE A CUSTOM FORMATTER
 
-The following data is kept up-to-date internally to be consumed by formatters:
+The following data is kept up-to-date internally, to be processed by
+formatters:
 
 >lua
     ---@class HarpoonLineData
     H.data = {
       --- @type string|nil
-      list_name = nil, -- the name of the list in use
+      list_name = nil, -- the name of the current list
       --- @type number
-      list_length = 0, -- the length of the list
+      list_length = 0, -- the length of the current list
       --- @type number|nil
-      buffer_idx = nil, -- the harpoon index of the current buffer if harpooned
+      buffer_idx = nil, -- the mark of the current buffer if harpooned
     }
 <
 
@@ -253,15 +273,16 @@ Example:
     local Harpoonline = require("harpoonline")
     Harpoonline.setup({
       custom_formatter = Harpoonline.gen_formatter(
-        function(data, _)
-          return string.format(
+        ---@param data HarpoonLineData
+        ---@return string
+        function(data)
+          return string.format( -- very short, without the length of the harpoon list
             "%s%s%s",
             "➡️ ",
             data.list_name and string.format("%s ", data.list_name) or "",
             data.buffer_idx and string.format("%d", data.buffer_idx) or "-"
           )
-        end,
-        {}
+        end
       ),
     })
 <
@@ -276,18 +297,20 @@ example recipe for NvChad.
 
 HARPOON LISTS                          *harpoonline-harpoonline-harpoon-lists*
 
-This plugin provides support for working with multiple harpoon lists.
+This plugin supports working with multiple harpoon lists. The list in use when
+Neovim is started is assumed to be the default list
 
-The list in use when Neovim is started is assumed to be the default list
+**Important**:
 
 The plugin needs to be notified when switching to another list using its custom
 `HarpoonSwitchedList` event:
 
 >lua
-    local list_name = nil -- starts with the default
+     -- Starts with the default. Use this variable in harpoon:list(list_name)
+    local list_name = nil
 
     vim.keymap.set("n", "<leader>J", function()
-      -- toggle between the current list and list "custom"
+      -- toggle between the default list and list "custom"
       list_name = list_name ~= "custom" and "custom" or nil
       vim.api.nvim_exec_autocmds("User",
         { pattern = "HarpoonSwitchedList", modeline = false, data = list_name })