From 5e4cf8bec6d7de94ee2152ca8dddf891e92abf2c Mon Sep 17 00:00:00 2001
From: James Trew <j.trew10@gmail.com>
Date: Sun, 21 Jul 2024 13:31:05 -0400
Subject: [PATCH] docs: switch out docgen tools

- deprecate `tree-sitter-lua` docgen for `docgen.nvim`
- update docs and add type annotations
- update ci config slightly
---
 .gitignore                                    |   2 +-
 Makefile                                      |  11 +-
 lua/telescope/_extensions/file_browser.lua    |  35 +--
 .../_extensions/file_browser/actions.lua      |  72 ++++---
 .../_extensions/file_browser/finders.lua      |  50 ++---
 .../_extensions/file_browser/make_entry.lua   |   4 +-
 .../_extensions/file_browser/picker.lua       | 199 ++++++++++++------
 .../_extensions/file_browser/utils.lua        |   2 +-
 scripts/gendocs.lua                           |  37 ++--
 scripts/minimal_init.vim                      |   5 +-
 10 files changed, 237 insertions(+), 180 deletions(-)

diff --git a/.gitignore b/.gitignore
index 7aa68e81..0d262eb7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,2 @@
 doc/tags
-deps/
+.deps/
diff --git a/Makefile b/Makefile
index 183d7101..6b2f073f 100644
--- a/Makefile
+++ b/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' }"
diff --git a/lua/telescope/_extensions/file_browser.lua b/lua/telescope/_extensions/file_browser.lua
index 957afb76..c84a3c54 100644
--- a/lua/telescope/_extensions/file_browser.lua
+++ b/lua/telescope/_extensions/file_browser.lua
@@ -1,6 +1,4 @@
----@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.
 ---
@@ -8,7 +6,7 @@
 --- 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()
diff --git a/lua/telescope/_extensions/file_browser/actions.lua b/lua/telescope/_extensions/file_browser/actions.lua
index e81af9ed..c87247d8 100755
--- a/lua/telescope/_extensions/file_browser/actions.lua
+++ b/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
diff --git a/lua/telescope/_extensions/file_browser/finders.lua b/lua/telescope/_extensions/file_browser/finders.lua
index 25e3ba21..2c9afc46 100644
--- a/lua/telescope/_extensions/file_browser/finders.lua
+++ b/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"
@@ -80,11 +76,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
@@ -137,12 +130,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 }
@@ -166,29 +157,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)
@@ -227,8 +207,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),
   }, {
diff --git a/lua/telescope/_extensions/file_browser/make_entry.lua b/lua/telescope/_extensions/file_browser/make_entry.lua
index f57776b4..bb902add 100644
--- a/lua/telescope/_extensions/file_browser/make_entry.lua
+++ b/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
diff --git a/lua/telescope/_extensions/file_browser/picker.lua b/lua/telescope/_extensions/file_browser/picker.lua
index 3fa1e497..e69329fa 100644
--- a/lua/telescope/_extensions/file_browser/picker.lua
+++ b/lua/telescope/_extensions/file_browser/picker.lua
@@ -1,17 +1,48 @@
----@tag telescope-file-browser.picker
----@config { ["module"] = "telescope-file-browser.picker" }
-
----@brief [[
+---@brief
 --- You can use the file browser as follows
---- <code>
---- :lua vim.api.nvim_set_keymap(
----    "n",
----    "<space>fb",
----    "<cmd>lua require 'telescope'.extensions.file_browser.file_browser()<CR>",
----    {noremap = true}
+---
+--- ```lua
+--- vim.keymap.set(
+---   "n",
+---   "<space>fb",
+---   "<cmd>Telescope file_browser<CR>",
+---   { noremap = true }
 --- )
---- </code>
----@brief ]]
+---
+--- -- or alternatively using lua functions
+--- local picker = require "telescope._extensions.file_browser"
+--- vim.api.keymap.set("n", "<space>fb", function()
+---   picker.file_browser()
+--- end, { noremap = true })
+--- ```
+--- The `file_browser` picker comes pre-configured with several keymaps:
+--- - `<cr>`   : Opens the currently selected file/directory, or creates whatever is in the prompt
+--- - `<s-cr>` : Create path in prompt
+--- - `/`, `\` : (OS Path separator) When typing filepath, the path separator will open a directory like `<cr>`.
+--- - `<A-c>/c`: Create file/folder at current `path` (trailing path separator creates folder)
+--- - `<A-r>/r`: Rename multi-selected files/folders
+--- - `<A-m>/m`: Move multi-selected files/folders to current `path`
+--- - `<A-y>/y`: Copy (multi-)selected files/folders to current `path`
+--- - `<A-d>/d`: Delete (multi-)selected files/folders
+--- - `<C-o>/o`: Open file/folder with default system application
+--- - `<C-g>/g`: Go to parent directory
+--- - `<C-e>/e`: Go to home directory
+--- - `<C-w>/w`: Go to current working directory (cwd)
+--- - `<C-t>/t`: Change nvim's cwd to selected folder/file(parent)
+--- - `<C-f>/f`: Toggle between file and folder browser
+--- - `<C-h>/h`: Toggle hidden files/folders
+--- - `<C-s>/s`: Toggle all entries ignoring `./` and `../`
+--- - `<bs>/`  : Goes to parent dir if prompt is empty, otherwise acts normally
+---
+---
+--- <br>The file browser picker can be configured with the following options:
+
+vim.keymap.set(
+  "n",
+  "<space>fb",
+  "<cmd>Telescope file_browser<CR>",
+  { noremap = true }
+)
 
 local pickers = require "telescope.pickers"
 local conf = require("telescope.config").values
@@ -27,65 +58,101 @@ local fb_picker = {}
 
 -- try to get the index of entry of current buffer
 
---- List, create, delete, rename, or move files and folders of your cwd.<br>
---- Notes
---- - Default keymaps in insert/normal mode:
----   - `<cr>`   : Opens the currently selected file/directory, or creates whatever is in the prompt
----   - `<s-cr>` : Create path in prompt
----   - `/`, `\` : (OS Path separator) When typing filepath, the path separator will open a directory like `<cr>`.
----   - `<A-c>/c`: Create file/folder at current `path` (trailing path separator creates folder)
----   - `<A-r>/r`: Rename multi-selected files/folders
----   - `<A-m>/m`: Move multi-selected files/folders to current `path`
----   - `<A-y>/y`: Copy (multi-)selected files/folders to current `path`
----   - `<A-d>/d`: Delete (multi-)selected files/folders
----   - `<C-o>/o`: Open file/folder with default system application
----   - `<C-g>/g`: Go to parent directory
----   - `<C-e>/e`: Go to home directory
----   - `<C-w>/w`: Go to current working directory (cwd)
----   - `<C-t>/t`: Change nvim's cwd to selected folder/file(parent)
----   - `<C-f>/f`: Toggle between file and folder browser
----   - `<C-h>/h`: Toggle hidden files/folders
----   - `<C-s>/s`: Toggle all entries ignoring `./` and `../`
----   - `<bs>/`  : Goes to parent dir if prompt is empty, otherwise acts normally
---- - display_stat:
----   - A table that can currently hold `date` and/or `size` as keys -- order matters!
----   - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
----   - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
----   - The flags can be incrementally changed via eg { date = true, size = { width = 20, hl = "ErrorMsg" } }
----   - See make_entry.lua for an example on how to further customize
+--- Options for the base telescope picker.
 ---
----@param opts table: options to pass to the picker
----@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: vim.loop.cwd())
----@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: vim.loop.cwd())
----@field cwd_to_path boolean: whether folder browser is launched from `path` rather than `cwd` (default: false)
----@field grouped boolean: group initial sorting by directories and then files (default: false)
----@field files boolean: start in file (true) or folder (false) browser (default: true)
----@field add_dirs boolean: whether the file browser shows folders (default: true)
----@field depth number: file tree depth to display, `false` for unlimited depth (default: 1)
----@field auto_depth boolean|number: unlimit or set `depth` to `auto_depth` & unset grouped on prompt for file_browser (default: false)
----@field select_buffer boolean: select current buffer if possible; may imply `hidden=true` (default: false)
+--- This should eventually be moved up to telescope core
+---@nodoc
+---@class telescope.picker.opts
+---@field prompt_title string? title of the prompt window
+---@field results_title string? title of the results windows
+---@field preview_title string? title of the preview window
+---@field prompt_prefix string? prefix of the prompt
+---@field wrap_results boolean?
+---@field selection_caret string?
+---@field entry_prefix string?
+---@field multi_icon string?
+---@field initial_mode ('insert'|'normal')?
+---@field debounce number?
+---@field default_text string?
+---@field get_status_text (fun(picker: table): string)?
+---@field on_input_filter_cb (fun(prompt: string): any)?
+---@field finder table?
+---@field sorter Sorter?
+---@field previewer (table)?
+---@field current_previewer_index number?
+---@field default_selection_index number?
+---@field get_selection_window (fun(picker: table, entry: table): number)?
+---@field cwd string?
+---@field _completion_callbacks ((fun(picker: table): nil)[])?
+---@field manager table?
+---@field _multi table?
+---@field track boolean?
+---@field attach_mappings (fun(prompt_bufnr: integer, map: fun()): boolean)?
+---@field file_ignore_patterns (string[])?
+---@field scroll_strategy ('cycle'|'limit')?
+---@field sorting_strategy ('descending'|'ascending')?
+---@field tiebreak (fun(current_entry: any, existing_entry: any, prompt: string): boolean)?
+---@field selection_strategy ('reset'|'follow'|'row'|'closest'|'none')?
+---@field push_cursor_on_edit boolean?
+---@field push_tagstack_on_edit boolean?
+---@field layout_strategy ('horizontal'|'vertical'|'center'|'cursor'|'flex'|'bottom_pane')?
+---@field layout_config table?
+---@field cycle_layout_list (string[])?
+---@field winblend number?
+---@field window table?
+---@field border boolean?
+---@field borderchars (string[])?
+
+--- Options for the file browser picker.
+---
+--- Inherits options for the base telescope picker.<br>
+--- See |telescope.defaults|
+---
+--- Notes:
+--- - display_stat:
+---     - A table that can currently hold `date` and/or `size` as keys -- order matters!
+---     - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
+---     - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
+---     - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }`
+---     - See make_entry.lua for an example on how to further customize
+---@class telescope-file-browser.PickerOpts : telescope.picker.opts
+---@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
+---@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
+---@field cwd_to_path boolean: whether folder browser is launched from `path` rather than `cwd` (default: `false`)
+---@field grouped boolean: group initial sorting by directories and then files (default: `false`)
+---@field files boolean: start in file (true) or folder (false) browser (default: `true`)
+---@field add_dirs boolean: whether the file browser shows folders (default: `true`)
+---@field depth number: file tree depth to display, `false` for unlimited depth (default: `1`)
+---@field auto_depth boolean|number: unlimit or set `depth` to `auto_depth` & unset grouped on prompt for file_browser (default: `false`)
+---@field select_buffer boolean: select current buffer if possible; may imply `hidden=true` (default: `false`)
 ---@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 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 browse_files function: custom override for the file browser (default: |fb_finders.browse_files|)
 ---@field browse_folders function: custom override for the folder browser (default: |fb_finders.browse_folders|)
----@field hide_parent_dir boolean: hide `../` in the file browser (default: false)
----@field collapse_dirs boolean: skip dirs w/ only single (possibly hidden) sub-dir in file_browser (default: false)
----@field quiet boolean: surpress any notification from file_brower actions (default: false)
----@field use_ui_input boolean: Use vim.ui.input() instead of vim.fn.input() or vim.fn.confirm() (default: true)
----@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 hide_parent_dir boolean: hide `../` in the file browser (default: `false`)
+---@field collapse_dirs boolean: skip dirs w/ only single (possibly hidden) sub-dir in file_browser (default: `false`)
+---@field quiet boolean: surpress any notification from file_brower actions (default: `false`)
+---@field use_ui_input boolean: Use vim.ui.input() instead of vim.fn.input() or vim.fn.confirm() (default: `true`)
+---@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 display_stat boolean|table: ordered stat; see above notes, (default: `{ date = true, size = true, mode = true }`)
----@field hijack_netrw boolean: use telescope file browser when opening directory paths; must be set on `setup` (default: false)
----@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 if `git` executable can be found)
----@field prompt_path boolean: Show the current relative path from cwd as the prompt prefix. (default: false)
----@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: true)
+---@field hijack_netrw boolean: use telescope file browser when opening directory paths; must be set on `setup` (default: `false`)
+---@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` if `git` executable can be found)
+---@field prompt_path boolean: Show the current relative path from cwd as the prompt prefix. (default: `false`)
+---@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: `true`)
+---@field theme string?: theme to use for the file browser (default: `nil`)
+---@field _custom_prompt_title boolean
+---@field _custom_results_title boolean
+
+--- Create a new file browser picker.
+---@param opts telescope-file-browser.PickerOpts?: options to pass to the picker
 fb_picker.file_browser = function(opts)
   opts = opts or {}
 
-  local cwd = vim.loop.cwd()
+  local cwd = vim.loop.cwd() ---@cast cwd string
   opts.depth = vim.F.if_nil(opts.depth, 1)
   opts.cwd_to_path = vim.F.if_nil(opts.cwd_to_path, false)
   opts.cwd = opts.cwd and fb_utils.to_absolute_path(opts.cwd) or cwd
@@ -95,8 +162,8 @@ fb_picker.file_browser = function(opts)
   opts.hide_parent_dir = vim.F.if_nil(opts.hide_parent_dir, false)
   opts.select_buffer = vim.F.if_nil(opts.select_buffer, false)
   opts.display_stat = vim.F.if_nil(opts.display_stat, { mode = true, date = true, size = true })
-  opts.custom_prompt_title = opts.prompt_title ~= nil
-  opts.custom_results_title = opts.results_title ~= nil
+  opts._custom_prompt_title = opts.prompt_title ~= nil
+  opts._custom_results_title = opts.results_title ~= nil
   opts.use_fd = vim.F.if_nil(opts.use_fd, true)
   opts.git_status = vim.F.if_nil(opts.git_status, vim.fn.executable "git" == 1)
   opts.prompt_path = vim.F.if_nil(opts.prompt_path, false)
@@ -105,6 +172,8 @@ fb_picker.file_browser = function(opts)
   local select_buffer = opts.select_buffer and opts.files
   -- handle case that current buffer is a hidden file
   opts.hidden = (select_buffer and vim.fn.expand("%:p:t"):sub(1, 1) == ".") and true or opts.hidden
+
+  ---@cast opts telescope-file-browser.FinderOpts
   opts.finder = fb_finder.finder(opts)
   -- find index of current buffer in the results
   if select_buffer then
diff --git a/lua/telescope/_extensions/file_browser/utils.lua b/lua/telescope/_extensions/file_browser/utils.lua
index 1f45ce7d..9a275330 100644
--- a/lua/telescope/_extensions/file_browser/utils.lua
+++ b/lua/telescope/_extensions/file_browser/utils.lua
@@ -189,7 +189,7 @@ end
 ---@return string
 fb_utils.sanitize_path_str = function(path)
   path = path:gsub(os_sep .. os_sep, os_sep)
-  if iswin then
+  if fb_utils.iswin then
     if path:match "^%w:\\$" then
       return path
     else
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 3188b983..ae76158f 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -1,27 +1,22 @@
-local docgen = require "docgen"
+vim.env.DOCGEN_PATH = vim.env.DOCGEN_PATH or ".deps/docgen.nvim"
 
-local docs = {}
+load(vim.fn.system "curl -s https://raw.githubusercontent.com/jamestrew/docgen.nvim/master/scripts/bootstrap.lua")()
 
-docs.test = function()
-  local input_files = {
+require("docgen").run {
+  name = "telescope-file-browser",
+  files = {
     "./lua/telescope/_extensions/file_browser.lua",
     "./lua/telescope/_extensions/file_browser/picker.lua",
     "./lua/telescope/_extensions/file_browser/actions.lua",
     "./lua/telescope/_extensions/file_browser/finders.lua",
-  }
-
-  local output_file = "./doc/telescope-file-browser.txt"
-  local output_file_handle = io.open(output_file, "w")
-
-  for _, input_file in ipairs(input_files) do
-    docgen.write(input_file, output_file_handle)
-  end
-
-  output_file_handle:write " vim:tw=78:ts=8:ft=help:norl:\n"
-  output_file_handle:close()
-  vim.cmd [[checktime]]
-end
-
-docs.test()
-
-return docs
+  },
+  section_fmt = function(filename)
+    local section_names = {
+      ["./lua/telescope/_extensions/file_browser.lua"] = "TELESCOPE-FILE-BROWSER",
+      ["./lua/telescope/_extensions/file_browser/picker.lua"] = "PICKER",
+      ["./lua/telescope/_extensions/file_browser/actions.lua"] = "ACTIONS",
+      ["./lua/telescope/_extensions/file_browser/finders.lua"] = "FINDERS",
+    }
+    return section_names[filename]
+  end,
+}
diff --git a/scripts/minimal_init.vim b/scripts/minimal_init.vim
index 88a55925..c3c3e780 100644
--- a/scripts/minimal_init.vim
+++ b/scripts/minimal_init.vim
@@ -1,6 +1,5 @@
 set rtp+=.
-set rtp+=deps/plenary.nvim/
-set rtp+=deps/telescope.nvim/
-set rtp+=deps/tree-sitter-lua/
+set rtp+=.deps/plenary.nvim/
+set rtp+=.deps/telescope.nvim/
 
 runtime! plugin/plenary.vim