docs: switch out docgen tool

Author: jamestrew

.github/workflows/docgen.yml

@@ -17,7 +17,7 @@ jobs:
       matrix:
         include:
           - os: ubuntu-22.04
-            url: https://github.com/neovim/neovim/releases/download/v0.9.5/nvim-linux64.tar.gz
+            url: https://github.com/neovim/neovim/releases/download/v0.10.1/nvim-linux64.tar.gz
     steps:
       - uses: actions/checkout@v4
       - run: date +%F > todays-date
@@ -35,17 +35,8 @@ jobs:
           }
           mkdir -p ~/.local/share/nvim/site/pack/vendor/start
           git clone --depth 1 https://github.com/nvim-lua/plenary.nvim ~/.local/share/nvim/site/pack/vendor/start/plenary.nvim
-          git clone https://github.com/tjdevries/tree-sitter-lua ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
           ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start
 
-      - name: Build parser
-        run: |
-          # We have to build the parser every single time to keep up with parser changes
-          cd ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
-          git checkout 86f74dfb69c570f0749b241f8f5489f8f50adbea
-          make dist
-          cd -
-
       - name: Generating docs
         run: |
           export PATH="${PWD}/_neovim/bin:${PATH}"

Makefile

@@ -7,4 +7,4 @@ lint:
 	luacheck lua/telescope
 
 docgen:
-	nvim --headless --noplugin -u scripts/minimal_init.vim -c "luafile ./scripts/gendocs.lua" -c 'qa'
+	nvim -l scripts/gendocs.lua

doc/telescope.txt

@@ -1,27 +1,23 @@
----@tag telescope.actions.generate
----@config { ["module"] = "telescope.actions.generate", ["name"] = "ACTIONS_GENERATE" }
-
----@brief [[
+---@brief
 --- Module for convenience to override defaults of corresponding |telescope.actions| at |telescope.setup()|.
 ---
 --- General usage:
---- <code>
----   require("telescope").setup {
----     defaults = {
----       mappings = {
----         n = {
----           ["?"] = action_generate.which_key {
----             name_width = 20, -- typically leads to smaller floats
----             max_height = 0.5, -- increase potential maximum height
----             separator = " > ", -- change sep between mode, keybind, and name
----             close_with_action = false, -- do not close float on action
----           },
+--- ```lua
+--- require("telescope").setup {
+---   defaults = {
+---     mappings = {
+---       n = {
+---         ["?"] = action_generate.which_key {
+---           name_width = 20, -- typically leads to smaller floats
+---           max_height = 0.5, -- increase potential maximum height
+---           separator = " > ", -- change sep between mode, keybind, and name
+---           close_with_action = false, -- do not close float on action
 ---         },
 ---       },
 ---     },
----   }
---- </code>
----@brief ]]
+---   },
+--- }
+--- ```
 
 local actions = require "telescope.actions"
 local config = require "telescope.config"
@@ -30,12 +26,8 @@ local finders = require "telescope.finders"
 
 local action_generate = {}
 
---- Display the keymaps of registered actions similar to which-key.nvim.<br>
---- - Floating window:
----   - Appears on the opposite side of the prompt.
----   - Resolves to minimum required number of lines to show hints with `opts` or truncates entries at `max_height`.
----   - Closes automatically on action call and can be disabled with by setting `close_with_action` to false.
----@param opts table: options to pass to toggling registered actions
+---@inlinedoc
+---@class telescope.actions.generate.which_key.opts
 ---@field max_height number: % of max. height or no. of rows for hints (default: 0.4), see |resolver.resolve_height()|
 ---@field only_show_current_mode boolean: only show keymaps for the current mode (default: true)
 ---@field mode_width number: fixed width of mode to be shown (default: 1)
@@ -53,6 +45,13 @@ local action_generate = {}
 ---@field border_hl string: winhl of "Normal" for keymap borders (default: "TelescopePromptBorder")
 ---@field winblend number: pseudo-transparency of keymap hints floating window
 ---@field zindex number: z-index of keymap hints floating window (default: 100)
+
+--- Display the keymaps of registered actions similar to which-key.nvim.
+--- - Floating window:
+---   - Appears on the opposite side of the prompt.
+---   - Resolves to minimum required number of lines to show hints with `opts` or truncates entries at `max_height`.
+---   - Closes automatically on action call and can be disabled with by setting `close_with_action` to false.
+---@param opts table: options to pass to toggling registered actions
 action_generate.which_key = function(opts)
   local which_key = function(prompt_bufnr)
     actions.which_key(prompt_bufnr, opts)

lua/telescope/actions/generate.lua

@@ -4,10 +4,7 @@ local utils = require "telescope.utils"
 
 local uv = vim.loop
 
----@tag telescope.actions.history
----@config { ["module"] = "telescope.actions.history" }
-
----@brief [[
+---@brief
 --- A base implementation of a prompt history that provides a simple history
 --- and can be replaced with a custom implementation.
 ---
@@ -24,7 +21,6 @@ local uv = vim.loop
 --- - etc
 ---
 --- See https://github.com/nvim-telescope/telescope-smart-history.nvim
----@brief ]]
 
 -- TODO(conni2461): currently not present in plenary path only sync.
 -- But sync is just unnecessary here
@@ -57,12 +53,15 @@ local histories = {}
 histories.History = {}
 histories.History.__index = histories.History
 
---- Create a new History
----@param opts table: Defines the behavior of History
+---@inlinedoc
+---@class telescope.actions.history.opts
 ---@field init function: Will be called after handling configuration (required)
 ---@field append function: How to append a new prompt item (required)
 ---@field reset function: What happens on reset. Will be called when telescope closes (required)
 ---@field pre_get function: Will be called before a next or previous item will be returned (optional)
+
+--- Create a new History
+---@param opts table: Defines the behavior of History
 function histories.History:new(opts)
   local obj = {}
   if conf.history == false or type(conf.history) ~= "table" then

lua/telescope/actions/history.lua

@@ -1,7 +1,4 @@
----@tag telescope.actions
----@config { ["module"] = "telescope.actions" }
-
----@brief [[
+---@brief
 --- These functions are useful for people creating their own mappings.
 ---
 --- Actions can be either normal functions that expect the `prompt_bufnr` as
@@ -10,47 +7,46 @@
 --- (1) The `prompt_bufnr` of a normal function denotes the identifier of your
 --- picker which can be used to access the picker state. In practice, users
 --- most commonly access from both picker and global state via the following:
---- <code>
----   -- for utility functions
----   local action_state = require "telescope.actions.state"
+--- ```lua
+--- -- for utility functions
+--- local action_state = require "telescope.actions.state"
 ---
----   local actions = {}
----   actions.do_stuff = function(prompt_bufnr)
----     local current_picker = action_state.get_current_picker(prompt_bufnr) -- picker state
----     local entry = action_state.get_selected_entry()
----   end
---- </code>
+--- local actions = {}
+--- actions.do_stuff = function(prompt_bufnr)
+---   local current_picker = action_state.get_current_picker(prompt_bufnr) -- picker state
+---   local entry = action_state.get_selected_entry()
+--- end
+--- ```
 ---
 --- See |telescope.actions.state| for more information.
 ---
 --- (2) To transform a module of functions into a module of "action"s, you need
 --- to do the following:
---- <code>
----   local transform_mod = require("telescope.actions.mt").transform_mod
+--- ```lua
+--- local transform_mod = require("telescope.actions.mt").transform_mod
 ---
----   local mod = {}
----   mod.a1 = function(prompt_bufnr)
----     -- your code goes here
----     -- You can access the picker/global state as described above in (1).
----   end
+--- local mod = {}
+--- mod.a1 = function(prompt_bufnr)
+---   -- your code goes here
+---   -- You can access the picker/global state as described above in (1).
+--- end
 ---
----   mod.a2 = function(prompt_bufnr)
----     -- your code goes here
----   end
----   mod = transform_mod(mod)
+--- mod.a2 = function(prompt_bufnr)
+---   -- your code goes here
+--- end
+--- mod = transform_mod(mod)
 ---
----   -- Now the following is possible. This means that actions a2 will be executed
----   -- after action a1. You can chain as many actions as you want.
----   local action = mod.a1 + mod.a2
----   action(bufnr)
---- </code>
+--- -- Now the following is possible. This means that actions a2 will be executed
+--- -- after action a1. You can chain as many actions as you want.
+--- local action = mod.a1 + mod.a2
+--- action(bufnr)
+--- ```
 ---
 --- Another interesting thing to do is that these actions now have functions you
 --- can call. These functions include `:replace(f)`, `:replace_if(f, c)`,
 --- `replace_map(tbl)` and `enhance(tbl)`. More information on these functions
 --- can be found in the `developers.md` and `lua/tests/automated/action_spec.lua`
 --- file.
----@brief ]]
 
 local a = vim.api
 
@@ -156,7 +152,7 @@ actions.toggle_selection = function(prompt_bufnr)
 end
 
 --- Multi select all entries.
---- - Note: selected entries may include results not visible in the results pop up.
+---@note selected entries may include results not visible in the results pop up.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.select_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -193,7 +189,7 @@ actions.drop_all = function(prompt_bufnr)
 end
 
 --- Toggle multi selection for all entries.
---- - Note: toggled entries may include results not visible in the results pop up.
+---@note toggled entries may include results not visible in the results pop up.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.toggle_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -1255,8 +1251,7 @@ actions.remove_selected_picker = function(prompt_bufnr)
 end
 
 --- Display the keymaps of registered actions similar to which-key.nvim.<br>
---- - Notes:
----   - The defaults can be overridden via |action_generate.which_key|.
+---@note The defaults can be overridden via |action_generate.which_key|.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.which_key = function(prompt_bufnr, opts)
   opts = opts or {}

lua/telescope/actions/init.lua

@@ -1,9 +1,5 @@
----@tag telescope.actions.layout
----@config { ["module"] = "telescope.actions.layout", ["name"] = "ACTIONS_LAYOUT" }
-
----@brief [[
+---@brief
 --- The layout actions are actions to be used to change the layout of a picker.
----@brief ]]
 
 local action_state = require "telescope.actions.state"
 local state = require "telescope.state"
@@ -18,9 +14,8 @@ local action_layout = setmetatable({}, {
 })
 
 --- Toggle preview window.
---- - Note: preview window can be toggled even if preview is set to false.
----
---- This action is not mapped by default.
+---@note preview window can be toggled even if preview is set to false.
+---@note this action is not mapped by default.
 ---@param prompt_bufnr number: The prompt bufnr
 action_layout.toggle_preview = function(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
@@ -54,7 +49,7 @@ end
 --- Toggles the `prompt_position` option between "top" and "bottom".
 --- Checks if `prompt_position` is an option for the current layout.
 ---
---- This action is not mapped by default.
+---@note this action is not mapped by default.
 ---@param prompt_bufnr number: The prompt bufnr
 action_layout.toggle_prompt_position = function(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
@@ -87,7 +82,7 @@ end
 --- Toggles the `mirror` option between `true` and `false`.
 --- Checks if `mirror` is an option for the current layout.
 ---
---- This action is not mapped by default.
+---@note this action is not mapped by default.
 ---@param prompt_bufnr number: The prompt bufnr
 action_layout.toggle_mirror = function(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
@@ -138,13 +133,13 @@ end
 
 --- Cycles to the next layout in `cycle_layout_list`.
 ---
---- This action is not mapped by default.
+---@note this action is not mapped by default.
 ---@param prompt_bufnr number: The prompt bufnr
 action_layout.cycle_layout_next = get_cycle_layout(1)
 
 --- Cycles to the previous layout in `cycle_layout_list`.
 ---
---- This action is not mapped by default.
+---@note this action is not mapped by default.
 ---@param prompt_bufnr number: The prompt bufnr
 action_layout.cycle_layout_prev = get_cycle_layout(-1)
 

lua/telescope/actions/layout.lua

@@ -1,15 +1,11 @@
----@tag telescope.actions.set
----@config { ["module"] = "telescope.actions.set", ["name"] = "ACTIONS_SET" }
-
----@brief [[
+---@brief
 --- Telescope action sets are used to provide an interface for managing
 --- actions that all primarily do the same thing, but with slight tweaks.
 ---
 --- For example, when editing files you may want it in the current split,
 --- a vertical split, etc. Instead of making users have to overwrite EACH
 --- of those every time they want to change this behavior, they can instead
 --- replace the `set` itself and then it will work great and they're done.
----@brief ]]
 
 local a = vim.api
 

lua/telescope/actions/set.lua

@@ -1,29 +1,28 @@
----@tag telescope.actions.state
----@config { ["module"] = "telescope.actions.state", ["name"] = "ACTIONS_STATE" }
-
----@brief [[
+---@brief
 --- Functions to be used to determine the current state of telescope.
 ---
 --- Generally used from within other |telescope.actions|
----@brief ]]
 
 local global_state = require "telescope.state"
 local conf = require("telescope.config").values
 
 local action_state = {}
 
 --- Get the current entry
+---@return table # the selected entry
 function action_state.get_selected_entry()
   return global_state.get_global_key "selected_entry"
 end
 
 --- Gets the current line in the search prompt
+---@return string # the current line in the search prompt
 function action_state.get_current_line()
   return global_state.get_global_key "current_line" or ""
 end
 
 --- Gets the current picker
 ---@param prompt_bufnr number: The prompt bufnr
+---@return table # the current picker
 function action_state.get_current_picker(prompt_bufnr)
   return global_state.get_status(prompt_bufnr).picker
 end