docs: switch out docgen tools (#399)

* docs: switch out docgen tools

- deprecate `tree-sitter-lua` docgen for `docgen.nvim`
- update docs and add type annotations
- update ci config slightly

* [docgen] Update doc/telescope-file-browser.txt
skip-checks: true

---------

Co-authored-by: Github Actions <actions@github>

.gitignore

@@ -1,2 +1,2 @@
 doc/tags
-deps/
+.deps/

Makefile

@@ -1,7 +1,6 @@
 .PHONY: docgen test clean
 
-DEPS_DIR := deps
-TS_DIR := $(DEPS_DIR)/tree-sitter-lua
+DEPS_DIR := .deps
 PLENARY_DIR := $(DEPS_DIR)/plenary.nvim
 TELESCOPE_DIR := $(DEPS_DIR)/telescope.nvim
 
@@ -20,15 +19,11 @@ $(DEPS_DIR):
 plenary: | $(DEPS_DIR)
 	$(call git_clone_or_pull,$(PLENARY_DIR),https://github.com/nvim-lua/plenary.nvim)
 
-docgen-deps: plenary | $(DEPS_DIR)
-	$(call git_clone_or_pull,$(TS_DIR),https://github.com/tjdevries/tree-sitter-lua)
-	cd "$(TS_DIR)" && make dist
-
 test-deps: plenary | $(DEPS_DIR)
 	$(call git_clone_or_pull,$(TELESCOPE_DIR),https://github.com/nvim-telescope/telescope.nvim)
 
-docgen: docgen-deps
-	nvim --headless --noplugin -u scripts/minimal_init.vim -c "luafile ./scripts/gendocs.lua" -c 'qa'
+docgen: $(DEPS_DIR)
+	nvim -l scripts/gendocs.lua
 
 test: test-deps
 	nvim --headless --noplugin -u scripts/minimal_init.vim -c "PlenaryBustedDirectory lua/tests/ { minimal_init = './scripts/minimal_init.vim' }"

lua/telescope/_extensions/file_browser.lua

@@ -1,14 +1,12 @@
----@tag telescope-file-browser
----@config { ["module"] = "telescope-file-browser" }
----@brief [[
+---@brief
 --- `telescope-file-browser.nvim` is an extension for telescope.nvim. It helps you efficiently
 --- create, delete, rename, or move files powered by navigation from telescope.nvim.
 ---
 --- The `telescope-file-browser` is setup via the `telescope` extension interface.<br>
 --- You can manage the settings for the `telescope-file-browser` analogous to how you
 --- manage the settings of any other built-in picker of `telescope.nvim`.
 --- You do not need to set any of these options.
---- <code>
+--- ```lua
 --- require('telescope').setup {
 ---   extensions = {
 ---     file_browser = {
@@ -17,17 +15,19 @@
 ---     }
 ---   }
 --- }
---- </code>
+--- ```
+--- See |telescope-file-browser.SetupOpts| below for all available options.
+---
 --- To get telescope-file-browser loaded and working with telescope,
 --- you need to call load_extension, somewhere after setup function:
---- <code>
+--- ```lua
 --- telescope.load_extension "file_browser"
---- </code>
+--- ```
 ---
 --- The extension exports `file_browser`, `actions`, `finder`, `_picker` modules via telescope extensions:
---- <code>
+--- ```lua
 --- require "telescope".extensions.file_browser
---- </code>
+--- ```
 --- In particular:
 --- - `file_browser`: constitutes the main picker of the extension
 --- - `actions`: extension actions make accessible for remapping and custom usage
@@ -42,9 +42,6 @@
 ---   :h |telescope-file-browser.actions|
 ---   :h |telescope-file-browser.finders|
 --- </pre>
----@brief ]]
-
----@tag telescope-file-browser.nvim
 
 local has_telescope, telescope = pcall(require, "telescope")
 if not has_telescope then
@@ -56,6 +53,20 @@ local fb_finders = require "telescope._extensions.file_browser.finders"
 local fb_picker = require "telescope._extensions.file_browser.picker"
 local fb_config = require "telescope._extensions.file_browser.config"
 
+---@class telescope-file-browser.SetupOpts : telescope-file-browser.PickerOpts
+--- use telescope file browser when opening directory paths (default: `false`)
+---@field hijack_netrw boolean?
+---@field theme string?: theme to use for the file browser (default: `nil`)
+--- define custom mappings for the file browser
+---
+--- See:
+--- - |telescope-file-browser.picker| for preconfigured file browser specific mappings
+--- - |telescope-file-browser.actions| for all available file browser specific actions
+--- - |telescope.mappings| and |telescope.actions| for general telescope mappings/actions and implementation details
+--- By default,
+---@field mappings table<string, table<string, function>>?
+
+---@param opts telescope-file-browser.SetupOpts?: telescope-file-brower setup options
 local file_browser = function(opts)
   opts = opts or {}
   local defaults = (function()

lua/telescope/_extensions/file_browser/actions.lua

@@ -1,12 +1,9 @@
----@tag telescope-file-browser.actions
----@config { ["module"] = "telescope-file-browser.actions" }
-
----@brief [[
+---@brief
 --- The file browser actions are functions enable file system operations from within the file browser picker.
 --- In particular, the actions include creation, deletion, renaming, and moving of files and folders.
 ---
 --- You can remap actions as follows:
---- <code>
+--- ```lua
 --- local fb_actions = require "telescope".extensions.file_browser.actions
 --- require('telescope').setup {
 ---   extensions = {
@@ -23,8 +20,7 @@
 ---     }
 ---   }
 --- }
---- </code>
----@brief ]]
+--- ```
 
 local a = vim.api
 
@@ -43,6 +39,7 @@ local popup = require "plenary.popup"
 local scan = require "plenary.scandir"
 local async = require "plenary.async"
 
+---@package
 local fb_actions = setmetatable({}, {
   __index = function(_, k)
     error("Key does not exist for 'fb_actions': " .. tostring(k))
@@ -134,11 +131,11 @@ end
 
 --- Creates a new file or dir in the current directory of the |telescope-file-browser.picker.file_browser|.
 --- - Finder:
----   - file_browser: create a file in the currently opened directory
----   - folder_browser: create a file in the currently selected directory
+---     - file_browser: create a file in the currently opened directory
+---     - folder_browser: create a file in the currently selected directory
 --- - Notes:
----   - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
----   - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
+---     - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
+---     - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.create = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -160,8 +157,8 @@ end
 
 --- Creates a new file or dir via prompt in the current directory of the |telescope-file-browser.picker.file_browser|.
 --- - Notes:
----   - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
----   - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
+---     - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
+---     - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.create_from_prompt = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -250,9 +247,10 @@ local batch_rename = function(prompt_bufnr, selections)
   ))
 end
 
---- Rename files or folders for |telescope-file-browser.picker.file_browser|.<br>
+--- Rename files or folders for |telescope-file-browser.picker.file_browser|.
+---
 --- Notes:
---- - Triggering renaming with multi selections opens `Batch Rename` window<br>
+--- - Triggering renaming with multi selections opens `Batch Rename` window
 ---   in which the user can rename/move files multi-selected files at once
 --- - In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged
 ---@param prompt_bufnr number: The prompt bufnr
@@ -324,12 +322,13 @@ fb_actions.rename = function(prompt_bufnr)
   end
 end
 
---- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|.<br>
+--- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|.
+---
 --- - Notes:
----   - Performs a blocking synchronized file-system operation.
----   - Moving multi-selections is sensitive to order of selection,
----     which potentially unpacks files from parent(s) dirs
----     if files are selected first.
+---     - Performs a blocking synchronized file-system operation.
+---     - Moving multi-selections is sensitive to order of selection,
+---       which potentially unpacks files from parent(s) dirs
+---       if files are selected first.
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.move = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -380,10 +379,11 @@ fb_actions.move = function(prompt_bufnr)
   current_picker:refresh(current_picker.finder, { reset_prompt = true })
 end
 
---- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|.<br>
+--- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|.
+---
 --- - Finder:
----   - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
----   - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
+---     - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
+---     - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.copy = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -477,7 +477,8 @@ fb_actions.copy = function(prompt_bufnr)
   fb_utils.selection_callback(current_picker, last_copied)
 end
 
---- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|.<br>
+--- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|.
+---
 --- Note: Performs a blocking synchronized file-system operation.
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.remove = function(prompt_bufnr)
@@ -571,13 +572,15 @@ fb_actions.toggle_respect_gitignore = function(prompt_bufnr)
   current_picker:refresh(finder, { reset_prompt = true, multi = current_picker._multi })
 end
 
---- Opens the file or folder with the default application.<br>
+--- Opens the file or folder with the default application.
+---
 --- - Notes:
----   - map fb_actions.open + fb_actions.close if you want to close the picker post-action
+---     - map fb_actions.open + fb_actions.close if you want to close the picker post-action
 --- - OS: make sure your OS links against the desired applications:
----   - Linux: induces application via `xdg-open`
----   - macOS: relies on `open` to start the program
----   - Windows: defaults to default applications through `start`
+---     - Linux: induces application via `xdg-open`
+---     - macOS: relies on `open` to start the program
+---     - Windows: defaults to default applications through `start`
+---@pram prompt_bufnr number: The prompt bufnr
 fb_actions.open = function(prompt_bufnr)
   local quiet = action_state.get_current_picker(prompt_bufnr).finder.quiet
   local selections = fb_utils.get_selected_files(prompt_bufnr, true)
@@ -713,8 +716,8 @@ end
 
 --- Multi select all entries akin to |telescope.actions.select_all| but ignores parent & current directory
 --- - Note:
----   - selected entries may include results not visible in the results popup.
----   - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
+---     - selected entries may include results not visible in the results popup.
+---     - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
 ---@param prompt_bufnr number: The prompt bufnr
 fb_actions.select_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -784,6 +787,7 @@ end
 
 --- Toggle sorting by last change to the entry.<br>
 --- Note: initially sorts desendingly from most to least recently changed entry.
+---@param prompt_bufnr number: The prompt bufnr
 fb_actions.sort_by_date = function(prompt_bufnr)
   local finder = action_state.get_current_picker(prompt_bufnr).finder
   finder.__sort_date = not finder.__sort_date
@@ -806,6 +810,8 @@ fb_actions.sort_by_date = function(prompt_bufnr)
 end
 
 --- If the prompt is empty, goes up to parent dir. Otherwise, acts as normal.
+---@param prompt_bufnr number: The prompt bufnr
+---@param bypass boolean: Allow passing beyond the globally set current working directory
 fb_actions.backspace = function(prompt_bufnr, bypass)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
 
@@ -816,6 +822,8 @@ fb_actions.backspace = function(prompt_bufnr, bypass)
   end
 end
 
+--- When a path separator is entered, navigate to the directory in the prompt.
+---@param prompt_bufnr number: The prompt bufnr
 fb_actions.path_separator = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   local dir = Path:new(current_picker.finder.path .. os_sep .. current_picker:_get_prompt() .. os_sep)
@@ -858,7 +866,7 @@ local function open_dir_path(finder, path, upward)
   return path
 end
 
----comment open directory and refresh picker
+--- Open directory and refresh picker
 ---@param prompt_bufnr integer
 ---@param _ any select type
 ---@param dir string? priority dir path

lua/telescope/_extensions/file_browser/finders.lua

@@ -1,9 +1,5 @@
----@tag telescope-file-browser.finders
----@config { ["module"] = "telescope-file-browser.finders" }
-
----@brief [[
+---@brief
 --- The file browser finders power the picker with both a file and folder browser.
----@brief ]]
 
 local fb_utils = require "telescope._extensions.file_browser.utils"
 local fb_make_entry = require "telescope._extensions.file_browser.make_entry"
@@ -87,11 +83,8 @@ end
 
 --- Returns a finder that is populated with files and folders in `path`.
 --- - Notes:
----  - Uses `fd` if available for more async-ish browsing and speed-ups
----@param opts table: options to pass to the finder
----@field path string: root dir to browse from
----@field depth number: file tree depth to display, `false` for unlimited (default: 1)
----@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
+---    - Uses `fd` if available for more async-ish browsing and speed-ups
+---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
 fb_finders.browse_files = function(opts)
   opts = opts or {}
   -- returns copy with properly set cwd for entry maker
@@ -144,12 +137,10 @@ end
 
 --- Returns a finder that is populated with (sub-)folders of `cwd`.
 --- - Notes:
----  - Uses `fd` if available for more async-ish browsing and speed-ups
----@param opts table: options to pass to the finder
----@field cwd string: root dir to browse from
----@field depth number: file tree depth to display (default: 1)
----@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
+---    - Uses `fd` if available for more async-ish browsing and speed-ups
+---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
 fb_finders.browse_folders = function(opts)
+  opts = opts or {}
   -- returns copy with properly set cwd for entry maker
   local cwd = opts.cwd_to_path and opts.path or opts.cwd
   local entry_maker = opts.entry_maker { cwd = cwd }
@@ -173,29 +164,18 @@ fb_finders.browse_folders = function(opts)
   end
 end
 
+---@class telescope-file-browser.FinderOpts : telescope-file-browser.PickerOpts
+---@field entry_maker fun(opts: table): function entry maker for the finder (advanced)
+---@field _entry_cache table<string, table>
+
 --- Returns a finder that combines |fb_finders.browse_files| and |fb_finders.browse_folders| into a unified finder.
----@param opts table: options to pass to the picker
----@field path string: root dir to file_browse from (default: vim.loop.cwd())
----@field cwd string: root dir (default: vim.loop.cwd())
----@field cwd_to_path boolean: folder browser follows `path` of file browser
----@field files boolean: start in file (true) or folder (false) browser (default: true)
----@field grouped boolean: group initial sorting by directories and then files (default: false)
----@field depth number: file tree depth to display (default: 1)
----@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
----@field respect_gitignore boolean: induces slow-down w/ plenary finder (default: false, true if `fd` available)
----@field no_ignore boolean: disable use of ignore files like .gitignore/.ignore/.fdignore (default: false, requires `fd`)
----@field follow_symlinks boolean: traverse symbolic links, i.e. files and folders (default: false, only works with `fd`)
----@field hide_parent_dir boolean: hide `../` in the file browser (default: false)
----@field dir_icon string: change the icon for a directory (default: )
----@field dir_icon_hl string: change the highlight group of dir icon (default: "Default")
----@field use_fd boolean: use `fd` if available over `plenary.scandir` (default: true)
----@field git_status boolean: show the git status of files (default: true)
----@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: true)
+---@param opts telescope-file-browser.FinderOpts?: options to pass to the picker
+---@return table # telescope finder
 fb_finders.finder = function(opts)
   opts = opts or {}
   -- cache entries such that multi selections are maintained across {file, folder}_browsers
   -- otherwise varying metatables misalign selections
-  opts.entry_cache = {}
+  opts._entry_cache = {}
 
   local hidden_default = { file_browser = false, folder_browser = false }
   local hidden = vim.F.if_nil(opts.hidden, hidden_default)
@@ -234,8 +214,8 @@ fb_finders.finder = function(opts)
     close = function(self)
       self._finder = nil
     end,
-    prompt_title = opts.custom_prompt_title,
-    results_title = opts.custom_results_title,
+    prompt_title = opts._custom_prompt_title,
+    results_title = opts._custom_results_title,
     prompt_path = opts.prompt_path,
     use_fd = vim.F.if_nil(opts.use_fd, true),
   }, {

lua/telescope/_extensions/file_browser/make_entry.lua

@@ -249,7 +249,7 @@ local make_entry = function(opts)
 
     -- telescope-file-browser has to cache the entries to resolve multi-selections
     -- across multiple folders
-    local cached_entry = opts.entry_cache[absolute_path]
+    local cached_entry = opts._entry_cache[absolute_path]
     if cached_entry ~= nil then
       -- update the entry in-place to keep multi selections in tact
       cached_entry.ordinal = e.ordinal
@@ -258,7 +258,7 @@ local make_entry = function(opts)
       return cached_entry
     end
 
-    opts.entry_cache[absolute_path] = e
+    opts._entry_cache[absolute_path] = e
     return e -- entry
   end
 end