docs: rewrite readme and add missing config values + builtin opts

12 files changed, 627 insertions, 369 deletions

diff --git a/lua/telescope/actions/generate.lua b/lua/telescope/actions/generate.lua
index fafce8c..40fc4b7 100644
--- a/lua/telescope/actions/generate.lua
+++ b/lua/telescope/actions/generate.lua
@@ -3,8 +3,8 @@
 ---@brief [[
 --- Module for convenience to override defaults of corresponding |telescope.actions| at |telescope.setup()|.
 ---
---- <pre>
 --- General usage:
+--- <code>
 ---   require("telescope").setup {
 ---     defaults = {
 ---       mappings = {
@@ -19,7 +19,7 @@
 ---       },
 ---     },
 ---   }
---- </pre>
+--- </code>
 ---@brief ]]
 
 local actions = require "telescope.actions"
diff --git a/lua/telescope/actions/utils.lua b/lua/telescope/actions/utils.lua
index 7c8a3ac..4d0c17d 100644
--- a/lua/telescope/actions/utils.lua
+++ b/lua/telescope/actions/utils.lua
@@ -16,20 +16,21 @@ local utils = {}
 ---   - Indices are 1-indexed, whereas rows are 0-indexed.
 --- - Warning: `map_entries` has no return value.
 ---   - The below example showcases how to collect results
---- <pre>
+---
 --- Usage:
----     local action_state = require "telescope.actions.state"
----     local action_utils = require "telescope.actions.utils"
----     function entry_value_by_row()
----       local prompt_bufnr = vim.api.nvim_get_current_buf()
----       local current_picker = action_state.get_current_picker(prompt_bufnr)
----       local results = {}
----         action_utils.map_entries(prompt_bufnr, function(entry, index, row)
----         results[row] = entry.value
----       end)
----       return results
----     end
---- </pre>
+--- <code>
+---   local action_state = require "telescope.actions.state"
+---   local action_utils = require "telescope.actions.utils"
+---   function entry_value_by_row()
+---     local prompt_bufnr = vim.api.nvim_get_current_buf()
+---     local current_picker = action_state.get_current_picker(prompt_bufnr)
+---     local results = {}
+---       action_utils.map_entries(prompt_bufnr, function(entry, index, row)
+---       results[row] = entry.value
+---     end)
+---     return results
+---   end
+--- </code>
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param f function: Function to map onto entries of picker that takes (entry, index, row) as viable arguments
 function utils.map_entries(prompt_bufnr, f)
@@ -52,20 +53,21 @@ end
 ---   - Selected entries are returned in order of their selection.
 --- - Warning: `map_selections` has no return value.
 ---   - The below example showcases how to collect results
---- <pre>
+---
 --- Usage:
----     local action_state = require "telescope.actions.state"
----     local action_utils = require "telescope.actions.utils"
----     function selection_by_index()
----       local prompt_bufnr = vim.api.nvim_get_current_buf()
----       local current_picker = action_state.get_current_picker(prompt_bufnr)
----       local results = {}
----         action_utils.map_selections(prompt_bufnr, function(entry, index)
----         results[index] = entry.value
----       end)
----       return results
----     end
---- </pre>
+--- <code>
+---   local action_state = require "telescope.actions.state"
+---   local action_utils = require "telescope.actions.utils"
+---   function selection_by_index()
+---     local prompt_bufnr = vim.api.nvim_get_current_buf()
+---     local current_picker = action_state.get_current_picker(prompt_bufnr)
+---     local results = {}
+---       action_utils.map_selections(prompt_bufnr, function(entry, index)
+---       results[index] = entry.value
+---     end)
+---     return results
+---   end
+--- </code>
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param f function: Function to map onto selection of picker that takes (selection) as a viable argument
 function utils.map_selections(prompt_bufnr, f)
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 0f55467..34f0089 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -1,5 +1,7 @@
 ---@tag telescope.builtin
 
+---@config { ['field_heading'] = "Options" }
+
 ---@brief [[
 --- Telescope Builtins is a collection of community maintained pickers to support common workflows. It can be used as
 --- reference when writing PRs, Telescope extensions, your own custom pickers, or just as a discovery tool for all of
@@ -12,44 +14,16 @@
 --- To use any of Telescope's default options or any picker-specific options, call your desired picker by passing a lua
 --- table to the picker with all of the options you want to use. Here's an example with the live_grep picker:
 ---
---- <pre>
---- :lua require('telescope.builtin').live_grep({
----   prompt_title = 'find string in open buffers...',
----   grep_open_files = true
---- })
---- -- or with dropdown theme
---- :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
----   previewer = false
---- })
---- </pre>
----
---- You can also pass default configurations to builtin pickers. These options will also be added if
---- the picker is executed with `Telescope find_files`.
----
---- <pre>
---- require("telescope").setup {
----   pickers = {
----     buffers = {
----       show_all_buffers = true,
----       sort_lastused = true,
----       theme = "dropdown",
----       previewer = false,
----       mappings = {
----         i = {
----           ["<c-d>"] = require("telescope.actions").delete_buffer,
----           -- or right hand side can also be the name of the action as string
----           ["<c-d>"] = "delete_buffer",
----         },
----         n = {
----           ["<c-d>"] = require("telescope.actions").delete_buffer,
----         }
----       }
----     }
----   }
---- }
---- </pre>
----
---- This will use the default configuration options. Other configuration options are still in flux at the moment
+--- <code>
+---   :lua require('telescope.builtin').live_grep({
+---     prompt_title = 'find string in open buffers...',
+---     grep_open_files = true
+---   })
+---   -- or with dropdown theme
+---   :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
+---     previewer = false
+---   })
+--- </code>
 ---@brief ]]
 
 if 1 ~= vim.fn.has "nvim-0.5" then
@@ -79,28 +53,33 @@ end
 
 --- Search for a string and get results live as you type (respecting .gitignore)
 ---@param opts table: options to pass to the picker
----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs`
 ---@field search_dirs table: directory/directories to search in, mutually exclusive with `grep_open_files`
 ---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on
+---@field max_results number: define a upper result value
+---@field disable_coordinates boolean: don't show the line & row numbers (default: false)
 builtin.live_grep = require_on_exported_call("telescope.builtin.files").live_grep
 
 --- Searches for the string under your cursor in your current working directory
 ---@param opts table: options to pass to the picker
----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field search string: the query to search
 ---@field search_dirs table: directory/directories to search in
----@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default is false)
+---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default: false)
+---@field word_match string: can be set to `-w` to enable exact word matches
 ---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on
+---@field disable_coordinates boolean: don't show the line and row numbers (default: false)
+---@field sort_only_text boolean: only sort the text, not the file, line or row (default: false)
 builtin.grep_string = require_on_exported_call("telescope.builtin.files").grep_string
 
 --- Search for files (respecting .gitignore)
 ---@param opts table: options to pass to the picker
----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
----@field find_command table: command line arguments for `find_files` to use for the search, overrides default config
+---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field find_command table: command line arguments for `find_files` to use for the search, overrides default: config
 ---@field follow boolean: if true, follows symlinks (i.e. uses `-L` flag for the `find` command)
----@field hidden boolean: determines whether to show hidden files or not (default is false)
----@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default is false)
+---@field hidden boolean: determines whether to show hidden files or not (default: false)
+---@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default: false)
 ---@field search_dirs table: directory/directories to search in
 builtin.find_files = require_on_exported_call("telescope.builtin.files").find_files
 
@@ -116,31 +95,40 @@ builtin.fd = builtin.find_files
 ---       create the file `init.lua` inside of `lua/telescope` and will create the necessary folders (similar to how
 ---       `mkdir -p` would work) if they do not already exist
 ---@param opts table: options to pass to the picker
----@field cwd string: root dir to browse from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
----@field depth number: file tree depth to display (default is 1)
----@field dir_icon string: change the icon for a directory. default: 
----@field hidden boolean: determines whether to show hidden files or not (default is false)
+---@field cwd string: root dir to browse from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field depth number: file tree depth to display (default: 1)
+---@field dir_icon string: change the icon for a directory. (default: )
+---@field hidden boolean: determines whether to show hidden files or not (default: false)
 builtin.file_browser = require_on_exported_call("telescope.builtin.files").file_browser
 
 --- Lists function names, variables, and other symbols from treesitter queries
 --- - Default keymaps:
 ---   - `<C-l>`: show autocompletion menu to prefilter your query by kind of ts node you want to see (i.e. `:var:`)
----@field show_line boolean: if true, shows the row:column that the result is found at (default is true)
+---@field show_line boolean: if true, shows the row:column that the result is found at (default: true)
+---@field bufnr number: specify the buffer number where treesitter should run. (default: current buffer)
+---@field symbol_highlights table: string -> string. Matches symbol with hl_group
 builtin.treesitter = require_on_exported_call("telescope.builtin.files").treesitter
 
 --- Live fuzzy search inside of the currently open buffer
 ---@param opts table: options to pass to the picker
+---@field skip_empty_lines boolean: if true we dont display empty lines (default: false)
 builtin.current_buffer_fuzzy_find = require_on_exported_call("telescope.builtin.files").current_buffer_fuzzy_find
 
 --- Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags
 --- or update when introducing new changes)
 ---@param opts table: options to pass to the picker
+---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field ctags_file string: specify a particular ctags file to use
----@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default is true)
+---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true)
+---@field only_sort_tags boolean: if true we will only sort tags (default: false)
 builtin.tags = require_on_exported_call("telescope.builtin.files").tags
 
 --- Lists all of the tags for the currently open buffer, with a preview
 ---@param opts table: options to pass to the picker
+---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field ctags_file string: specify a particular ctags file to use
+---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true)
+---@field only_sort_tags boolean: if true we will only sort tags (default: false)
 builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files").current_buffer_tags
 
 --
@@ -154,8 +142,10 @@ builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files"
 --- - Default keymaps:
 ---   - `<cr>`: opens the currently selected file
 ---@param opts table: options to pass to the picker
----@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default is true)
----@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default is false)
+---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
+---@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default: true)
+---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default: false)
 builtin.git_files = require_on_exported_call("telescope.builtin.git").files
 
 --- Lists commits for current directory with diff preview
@@ -166,6 +156,7 @@ builtin.git_files = require_on_exported_call("telescope.builtin.git").files
 ---   - `<C-r>h`: resets current branch to selected commit using hard mode
 ---@param opts table: options to pass to the picker
 ---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
 builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits
 
 --- Lists commits for current buffer with diff preview
@@ -176,6 +167,7 @@ builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits
 ---   - `<c-t>`: opens a diff in a new tab
 ---@param opts table: options to pass to the picker
 ---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
 ---@field current_file string: specify the current file that should be used for bcommits (default: current buffer)
 builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommits
 
@@ -188,6 +180,8 @@ builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommit
 ---   - `<C-d>`: deletes the currently selected branch, with confirmation prompt before deletion
 ---   - `<C-y>`: merges the currently selected branch, with confirmation prompt before deletion
 ---@param opts table: options to pass to the picker
+---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
 builtin.git_branches = require_on_exported_call("telescope.builtin.git").branches
 
 --- Lists git status for current directory
@@ -195,12 +189,17 @@ builtin.git_branches = require_on_exported_call("telescope.builtin.git").branche
 ---   - `<Tab>`: stages or unstages the currently selected file
 ---   - `<cr>`: opens the currently selected file
 ---@param opts table: options to pass to the picker
+---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
+---@field git_icons table: string -> string. Matches name with icon (see source code, make_entry.lua git_icon_defaults)
 builtin.git_status = require_on_exported_call("telescope.builtin.git").status
 
 --- Lists stash items in current repository
 --- - Default keymaps:
 ---   - `<cr>`: runs `git apply` for currently selected stash
 ---@param opts table: options to pass to the picker
+---@field cwd string: specify the path of the repo
+---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
 builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash
 
 --
@@ -211,10 +210,28 @@ builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash
 
 --- Lists all of the community maintained pickers built into Telescope
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: true)
+---@field include_extensions boolean: if true will show the pickers of the installed extensions (default: false)
 builtin.builtin = require_on_exported_call("telescope.builtin.internal").builtin
 
+--- Opens the previous picker in the identical state (incl. multi selections)
+--- - Notes:
+---   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
+---@param opts table: options to pass to the picker
+---@field cache_index number: what picker to resume, where 1 denotes most recent (default: 1)
+builtin.resume = require_on_exported_call("telescope.builtin.internal").resume
+
+--- Opens a picker over previously cached pickers in there preserved states (incl. multi selections)
+--- - Default keymaps:
+---   - `<C-x>`: delete the selected cached picker
+--- - Notes:
+---   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
+---@param opts table: options to pass to the picker
+builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers
+
 --- Use the telescope...
 ---@param opts table: options to pass to the picker
+---@field show_pluto boolean: we love pluto (default: false, because its a hidden feature)
 builtin.planets = require_on_exported_call("telescope.builtin.internal").planets
 
 --- Lists symbols inside of `data/telescope-sources/*.json` found in your runtime path
@@ -233,14 +250,17 @@ builtin.commands = require_on_exported_call("telescope.builtin.internal").comman
 
 --- Lists items in the quickfix list, jumps to location on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.quickfix = require_on_exported_call("telescope.builtin.internal").quickfix
 
 --- Lists items from the current window's location list, jumps to location on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.loclist = require_on_exported_call("telescope.builtin.internal").loclist
 
 --- Lists previously open files, opens on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field only_cwd boolean: show only files in the cwd (default: false)
 builtin.oldfiles = require_on_exported_call("telescope.builtin.internal").oldfiles
 
 --- Lists commands that were executed recently, and reruns them on `<cr>`
@@ -255,46 +275,35 @@ builtin.command_history = require_on_exported_call("telescope.builtin.internal")
 ---@param opts table: options to pass to the picker
 builtin.search_history = require_on_exported_call("telescope.builtin.internal").search_history
 
---- Opens the previous picker in the identical state (incl. multi selections)
---- - Notes:
----   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
----@param opts table: options to pass to the picker
----@field cache_index number: what picker to resume, where 1 denotes most recent (default 1)
-builtin.resume = require_on_exported_call("telescope.builtin.internal").resume
-
---- Opens a picker over previously cached pickers in there preserved states (incl. multi selections)
---- - Default keymaps:
----   - `<C-x>`: delete the selected cached picker
---- - Notes:
----   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
----@param opts table: options to pass to the picker
-builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers
-
 --- Lists vim options, allows you to edit the current value on `<cr>`
 ---@param opts table: options to pass to the picker
 builtin.vim_options = require_on_exported_call("telescope.builtin.internal").vim_options
 
 --- Lists available help tags and opens a new window with the relevant help info on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field lang string: specify language (default: vim.o.helplang)
+---@field fallback boolean: fallback to en if language isn't installed (default: true)
 builtin.help_tags = require_on_exported_call("telescope.builtin.internal").help_tags
 
 --- Lists manpage entries, opens them in a help window on `<cr>`
 ---@param opts table: options to pass to the picker
----@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections
+---@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections (default: { "1" })
+---@field man_cmd function: that returns the man command. (Default: `apropos ""` on linux, `apropos " "` on macos)
 builtin.man_pages = require_on_exported_call("telescope.builtin.internal").man_pages
 
 --- Lists lua modules and reloads them on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field column_len number: define the max column len for the module name (default: dynamic, longest module name)
 builtin.reloader = require_on_exported_call("telescope.builtin.internal").reloader
 
 --- Lists open buffers in current neovim instance, opens selected buffer on `<cr>`
 ---@param opts table: options to pass to the picker
----@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default true)
----@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default false)
----@field only_cwd boolean: if true, only show buffers in the current working directory (default false)
----@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default false)
----@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default false)
----@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames
+---@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default: true)
+---@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default: false)
+---@field only_cwd boolean: if true, only show buffers in the current working directory (default: false)
+---@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default: false)
+---@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default: false)
+---@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames  (default: dynamic)
 builtin.buffers = require_on_exported_call("telescope.builtin.internal").buffers
 
 --- Lists available colorschemes and applies them on `<cr>`
@@ -334,10 +343,12 @@ builtin.spell_suggest = require_on_exported_call("telescope.builtin.internal").s
 
 --- Lists the tag stack for the current window, jumps to tag on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.tagstack = require_on_exported_call("telescope.builtin.internal").tagstack
 
 --- Lists items from Vim's jumplist, jumps to location on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumplist
 
 --
@@ -348,52 +359,73 @@ builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumpli
 
 --- Lists LSP references for word under the cursor, jumps to reference on `<cr>`
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
 builtin.lsp_references = require_on_exported_call("telescope.builtin.lsp").references
 
 --- Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
 ---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never"
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.lsp_definitions = require_on_exported_call("telescope.builtin.lsp").definitions
 
 --- Goto the definition of the type of the word under the cursor, if there's only one,
 --- otherwise show all options in Telescope
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
 ---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never"
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.lsp_type_definitions = require("telescope.builtin.lsp").type_definitions
 
 --- Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
 ---@field jump_type string: how to goto implementation if there is only one, values: "tab", "split", "vsplit", "never"
+---@field ignore_filename boolean: dont show filenames (default: true)
 builtin.lsp_implementations = require_on_exported_call("telescope.builtin.lsp").implementations
 
 --- Lists any LSP actions for the word under the cursor which can be triggered with `<cr>`
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
 builtin.lsp_code_actions = require_on_exported_call("telescope.builtin.lsp").code_actions
 
 --- Lists any LSP actions for a given range, that can be triggered with `<cr>`
 ---@param opts table: options to pass to the picker
+---@field timeout number: timeout for the sync call (default: 10000)
+---@field start_line number: where the code action starts (default: handled by :'<,'>Telescope lsp_range_code_actions)
+---@field start_line number: where the code action ends (default: handled by :'<,'>Telescope lsp_range_code_actions)
 builtin.lsp_range_code_actions = require_on_exported_call("telescope.builtin.lsp").range_code_actions
 
 --- Lists LSP document symbols in the current buffer
 --- - Default keymaps:
 ---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
 ---@param opts table: options to pass to the picker
----@field ignore_filename type: string with file to ignore
+---@field timeout number: timeout for the sync call (default: 10000)
+---@field ignore_filename boolean: dont show filenames (default: true)
+---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false)
 ---@field symbols string|table: filter results by symbol kind(s)
+---@field symbol_highlights table: string -> string. Matches symbol with hl_group
 builtin.lsp_document_symbols = require_on_exported_call("telescope.builtin.lsp").document_symbols
 
 --- Lists LSP document symbols in the current workspace
 --- - Default keymaps:
 ---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
 ---@param opts table: options to pass to the picker
----@field ignore_filename string: file(s) to ignore
+---@field query string: for what to query the workspace (default: "")
+---@field timeout number: timeout for the sync call (default: 10000)
+---@field ignore_filename boolean: dont show filenames (default: false)
+---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false)
 ---@field symbols string|table: filter results by symbol kind(s)
+---@field symbol_highlights table: string -> string. Matches symbol with hl_group
 builtin.lsp_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").workspace_symbols
 
 --- Dynamically lists LSP for all workspace symbols
 --- - Default keymaps:
 ---   - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
 ---@param opts table: options to pass to the picker
+---@field ignore_filename boolean: dont show filenames (default: false)
+---@field show_line boolean: if true, shows the content of the line the symbol is found on (default: false)
+---@field symbol_highlights table: string -> string. Matches symbol with hl_group
 builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").dynamic_workspace_symbols
 
 --- Lists LSP diagnostics for the current buffer
@@ -405,7 +437,7 @@ builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.buil
 ---@field severity string|number: filter diagnostics by severity name (string) or id (number)
 ---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number)
 ---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number)
----@field no_sign bool: hide LspDiagnosticSigns from Results (default is false)
+---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false)
 ---@field line_width number: set length of diagnostic entry text in Results
 builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.lsp").diagnostics
 
@@ -418,7 +450,7 @@ builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.l
 ---@field severity string|number: filter diagnostics by severity name (string) or id (number)
 ---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number)
 ---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number)
----@field no_sign bool: hide LspDiagnosticSigns from Results (default is false)
+---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false)
 ---@field line_width number: set length of diagnostic entry text in Results
 builtin.lsp_workspace_diagnostics = require_on_exported_call("telescope.builtin.lsp").workspace_diagnostics
 
diff --git a/lua/telescope/builtin/internal.lua b/lua/telescope/builtin/internal.lua
index cbacf97..ae3b10e 100644
--- a/lua/telescope/builtin/internal.lua
+++ b/lua/telescope/builtin/internal.lua
@@ -635,7 +635,7 @@ internal.reloader = function(opts)
   local package_list = vim.tbl_keys(package.loaded)
 
   -- filter out packages we don't want and track the longest package name
-  opts.column_len = 0
+  local column_len = 0
   for index, module_name in pairs(package_list) do
     if
       type(require(module_name)) ~= "table"
@@ -643,10 +643,11 @@ internal.reloader = function(opts)
       or package.searchpath(module_name, package.path) == nil
     then
       table.remove(package_list, index)
-    elseif #module_name > opts.column_len then
-      opts.column_len = #module_name
+    elseif #module_name > column_len then
+      column_len = #module_name
     end
   end
+  opts.column_len = vim.F.if_nil(opts.column_len, column_len)
 
   pickers.new(opts, {
     prompt_title = "Packages",
diff --git a/lua/telescope/command.lua b/lua/telescope/command.lua
index db75eb1..f75fdeb 100644
--- a/lua/telescope/command.lua
+++ b/lua/telescope/command.lua
@@ -166,7 +166,8 @@ local function run_command(args)
   end
 
   if string.len(theme) > 0 then
-    opts = themes[theme](opts)
+    local func = themes[theme] or themes["get_" .. theme]
+    opts = func(opts)
   end
 
   if string.len(extension_type) > 0 and extension_type ~= '"' then
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index c66278f..406d3c6 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -120,191 +120,247 @@ local layout_config_description = string.format(
 -- - first entry is the value
 -- - second entry is the description of the option
 
-local telescope_defaults = {
+local telescope_defaults = {}
+config.descriptions_order = {}
+local append = function(name, val, doc)
+  telescope_defaults[name] = { val, doc }
+  table.insert(config.descriptions_order, name)
+end
 
-  sorting_strategy = {
-    "descending",
-    [[
-    Determines the direction "better" results are sorted towards.
+append(
+  "sorting_strategy",
+  "descending",
+  [[
+  Determines the direction "better" results are sorted towards.
 
-    Available options are:
-    - "descending" (default)
-    - "ascending"]],
-  },
+  Available options are:
+  - "descending" (default)
+  - "ascending"]]
+)
 
-  selection_strategy = {
-    "reset",
-    [[
-    Determines how the cursor acts after each sort iteration.
+append(
+  "selection_strategy",
+  "reset",
+  [[
+  Determines how the cursor acts after each sort iteration.
 
-    Available options are:
-    - "reset" (default)
-    - "follow"
-    - "row"
-    - "closest"]],
-  },
+  Available options are:
+  - "reset" (default)
+  - "follow"
+  - "row"
+  - "closest"]]
+)
 
-  scroll_strategy = {
-    "cycle",
-    [[
-    Determines what happens you try to scroll past view of the picker.
+append(
+  "scroll_strategy",
+  "cycle",
+  [[
+  Determines what happens if you try to scroll past the view of the
+  picker.
 
-    Available options are:
-    - "cycle" (default)
-    - "limit"]],
-  },
+  Available options are:
+  - "cycle" (default)
+  - "limit"]]
+)
 
-  layout_strategy = {
-    "horizontal",
-    [[
-    Determines the default layout of Telescope pickers.
-    See |telescope.layout| for details of the available strategies.
+append(
+  "layout_strategy",
+  "horizontal",
+  [[
+  Determines the default layout of Telescope pickers.
+  See |telescope.layout| for details of the available strategies.
 
-    Default: 'horizontal']],
-  },
+  Default: 'horizontal']]
+)
 
-  layout_config = { layout_config_defaults, layout_config_description },
+append("layout_config", layout_config_defaults, layout_config_description)
 
-  winblend = { 0 },
+append(
+  "winblend",
+  0,
+  [[
+  Configure winblend for telescope floating windows. See |winblend| for
+  more information.
 
-  prompt_prefix = { "> ", [[
-    Will be shown in front of the prompt.
+  Default: 0]]
+)
 
-    Default: '> ']] },
+append(
+  "prompt_prefix",
+  "> ",
+  [[
+  The character(s) that will be shown in front of Telescope's prompt.
 
-  selection_caret = { "> ", [[
-    Will be shown in front of the selection.
+  Default: '> ']]
+)
 
-    Default: '> ']] },
+append(
+  "selection_caret",
+  "> ",
+  [[
+  The character(s) that will be shown in front of the current selection.
 
-  entry_prefix = {
-    "  ",
-    [[
-    Prefix in front of each result entry. Current selection not included.
 
-    Default: '  ']],
-  },
+  Default: '> ']]
+)
 
-  initial_mode = { "insert" },
+append(
+  "entry_prefix",
+  "  ",
+  [[
+  Prefix in front of each result entry. Current selection not included.
 
-  border = { true, [[
-    Boolean defining if borders are added to Telescope windows.
+  Default: '  ']]
+)
 
-    Default: true]] },
+append(
+  "initial_mode",
+  "insert",
+  [[
+  Determines in which mode telescope starts. Valid Keys:
+  `insert` and `normal`.
 
-  path_display = {
-    {},
-    [[
-    Determines how file paths are displayed
+  Default: "insert"]]
+)
 
-    path_display can be set to an array with a combination of:
-    - "hidden"    hide file names
-    - "tail"      only display the file name, and not the path
-    - "absolute"  display absolute paths
-    - "smart"     remove as much from the path as possible to only show
-                  the difference between the displayed paths
-    - "shorten"   only display the first character of each directory in
-                  the path
+append(
+  "border",
+  true,
+  [[
+  Boolean defining if borders are added to Telescope windows.
 
-    You can also specify the number of characters of each directory name
-    to keep by setting `path_display.shorten = num`.
-      e.g. for a path like
-        `alpha/beta/gamma/delta.txt`
-      setting `path_display.shorten = 1` will give a path like:
-        `a/b/g/delta.txt`
-      Similarly, `path_display.shorten = 2` will give a path like:
-        `al/be/ga/delta.txt`
+  Default: true]]
+)
 
-    path_display can also be set to 'hidden' string to hide file names
+append(
+  "path_display",
+  {},
+  [[
+  Determines how file paths are displayed
+
+  path_display can be set to an array with a combination of:
+  - "hidden"    hide file names
+  - "tail"      only display the file name, and not the path
+  - "absolute"  display absolute paths
+  - "smart"     remove as much from the path as possible to only show
+                the difference between the displayed paths
+  - "shorten"   only display the first character of each directory in
+                the path
+
+  You can also specify the number of characters of each directory name
+  to keep by setting `path_display.shorten = num`.
+    e.g. for a path like
+      `alpha/beta/gamma/delta.txt`
+    setting `path_display.shorten = 1` will give a path like:
+      `a/b/g/delta.txt`
+    Similarly, `path_display.shorten = 2` will give a path like:
+      `al/be/ga/delta.txt`
+
+  path_display can also be set to 'hidden' string to hide file names
+
+  path_display can also be set to a function for custom formatting of
+  the path display. Example:
+
+      -- Format path as "file.txt (path\to\file\)"
+      path_display = function(opts, path)
+        local tail = require("telescope.utils").path_tail(path)
+        return string.format("%s (%s)", tail, path)
+      end,
 
-    path_display can also be set to a function for custom formatting of
-    the path display. Example:
+  Default: {}]]
+)
 
-        -- Format path as "file.txt (path\to\file\)"
-        path_display = function(opts, path)
-          local tail = require("telescope.utils").path_tail(path)
-          return string.format("%s (%s)", tail, path)
-        end,
+append(
+  "borderchars",
+  { "─", "│", "─", "│", "╭", "╮", "╯", "╰" },
+  [[
+  Set the borderchars of telescope floating windows. It has to be a
+  table of 8 string values.
 
-    Default: {}]],
-  },
+  Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }]]
+)
 
-  borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } },
+append(
+  "get_status_text",
+  function(self)
+    local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
+    local yy = self.stats.processed or 0
+    if xx == 0 and yy == 0 then
+      return ""
+    end
 
-  get_status_text = {
-    function(self, opts)
-      local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
-      local yy = self.stats.processed or 0
-      if xx == 0 and yy == 0 then
-        return ""
-      end
+    -- local status_icon
+    -- if opts.completed then
+    --   status_icon = "✔️"
+    -- else
+    --   status_icon = "*"
+    -- end
+    return string.format("%s / %s", xx, yy)
+  end,
+  [[
+  A function that determines what the virtual text looks like.
+  Signature: function(picker) -> str
 
-      -- local status_icon
-      -- if opts.completed then
-      --   status_icon = "✔️"
-      -- else
-      --   status_icon = "*"
-      -- end
+  Default: function that shows current count / all]]
+)
 
-      return string.format("%s / %s ", xx, yy)
-    end,
-  },
+append(
+  "dynamic_preview_title",
+  false,
+  [[
+  Will change the title of the preview window dynamically, where it
+  is supported. For example, the preview window's title could show up as
+  the full filename.
 
-  dynamic_preview_title = {
-    false,
-    [[
-    Will change the title of the preview window dynamically, where it
-    is supported. Means the preview window will for example show the
-    full filename.
+  Default: false]]
+)
 
-    Default: false]],
+append(
+  "history",
+  {
+    path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
+    limit = 100,
+    handler = function(...)
+      return require("telescope.actions.history").get_simple_history(...)
+    end,
   },
+  [[
+  This field handles the configuration for prompt history.
+  By default it is a table, with default values (more below).
+  To disable history, set it to false.
 
-  history = {
-    {
-      path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
-      limit = 100,
-      handler = function(...)
-        return require("telescope.actions.history").get_simple_history(...)
-      end,
-    },
-    [[
-    This field handles the configuration for prompt history.
-    By default it is a table, with default values (more below).
-    To disable history, set it to false.
-
-    Currently mappings still need to be added, Example:
-      mappings = {
-        i = {
-          ["<C-Down>"] = require('telescope.actions').cycle_history_next,
-          ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
-        },
+  Currently mappings still need to be added, Example:
+    mappings = {
+      i = {
+        ["<C-Down>"] = require('telescope.actions').cycle_history_next,
+        ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
       },
+    },
 
-    Fields:
-      - path:    The path to the telescope history as string.
-                 default: stdpath("data")/telescope_history
-      - limit:   The amount of entries that will be written in the
-                 history.
-                 Warning: If limit is set to nil it will grown unbound.
-                 default: 100
-      - handler: A lua function that implements the history.
-                 This is meant as a developer setting for extensions to
-                 override the history handling, e.g.,
-                 https://github.com/nvim-telescope/telescope-smart-history.nvim,
-                 which allows context sensitive (cwd + picker) history.
-
-                 Default:
-                 require('telescope.actions.history').get_simple_history
-  ]],
-  },
+  Fields:
+    - path:    The path to the telescope history as string.
+               default: stdpath("data")/telescope_history
+    - limit:   The amount of entries that will be written in the
+               history.
+               Warning: If limit is set to nil it will grown unbound.
+               default: 100
+    - handler: A lua function that implements the history.
+               This is meant as a developer setting for extensions to
+               override the history handling, e.g.,
+               https://github.com/nvim-telescope/telescope-smart-history.nvim,
+               which allows context sensitive (cwd + picker) history.
+
+               Default:
+               require('telescope.actions.history').get_simple_history]]
+)
 
-  cache_picker = {
-    {
-      num_pickers = 1,
-      limit_entries = 1000,
-    },
-    [[
+append(
+  "cache_picker",
+  {
+    num_pickers = 1,
+    limit_entries = 1000,
+  },
+  [[
     This field handles the configuration for picker caching.
     By default it is a table, with default values (more below).
     To disable caching, set it to false.
@@ -323,117 +379,239 @@ local telescope_defaults = {
                           Default: 1
       - limit_entries:    The amount of entries that will be written in the
                           Default: 1000
-    ]],
-  },
+    ]]
+)
 
-  -- Builtin configuration
+append(
+  "vimgrep_arguments",
+  { "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" },
+  [[
+    Defines the command that will be used for `live_grep` and `grep_string`
+    pickers.
+    Hint: Make sure that color is currently set to `never` because we do
+    not yet interpret color codes
+    Hint 2: Make sure that these options are in your changes arguments:
+      "--no-heading", "--with-filename", "--line-number", "--column"
+    because we need them so the ripgrep output is in the correct format.
+
+    Default: {
+      "rg",
+      "--color=never",
+      "--no-heading",
+      "--with-filename",
+      "--line-number",
+      "--column",
+      "--smart-case"
+    }]]
+)
 
-  -- List that will be executed.
-  --    Last argument will be the search term (passed in during execution)
-  vimgrep_arguments = {
-    { "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" },
-  },
+append(
+  "use_less",
+  true,
+  [[
+  Boolean if less should be enabled in term_previewer (deprecated and
+  currently no longer used in the builtin pickers).
+
+  Default: true]]
+)
 
-  use_less = { true },
+append(
+  "set_env",
+  nil,
+  [[
+  Set an environment for term_previewer. A table of key values:
+  Example: { COLORTERM = "truecolor", ... }
+  Hint: Empty table is not allowed.
 
-  color_devicons = { true },
+  Default: nil]]
+)
 
-  set_env = { nil },
+append(
+  "color_devicons",
+  true,
+  [[
+  Boolean if devicons should be enabled or not.
+  Hint: Coloring only works if |termguicolors| is enabled.
+
+  Default: true]]
+)
+
+append(
+  "mappings",
+  {},
+  [[
+  Your mappings to override telescope's default mappings.
+
+  Format is:
+  {
+    mode = { ..keys }
+  }
+
+  where {mode} is the one character letter for a mode
+  ('i' for insert, 'n' for normal).
+
+  For example:
 
   mappings = {
-    {},
-    [[
-    Your mappings to override telescope's default mappings.
+    i = {
+      ["<esc>"] = require('telescope.actions').close,
+    },
+  }
 
-    Format is:
-    {
-      mode = { ..keys }
-    }
 
-    where {mode} is the one character letter for a mode
-    ('i' for insert, 'n' for normal).
+  To disable a keymap, put [map] = false
+    So, to not map "<C-n>", just put
 
+      ...,
+      ["<C-n>"] = false,
+      ...,
+
+    Into your config.
+
+
+  otherwise, just set the mapping to the function that you want it to
+  be.
+
+      ...,
+      ["<C-i>"] = require('telescope.actions').select_default,
+      ...,
+
+  If the function you want is part of `telescope.actions`, then you can
+  simply give a string.
+    For example, the previous option is equivalent to:
+
+      ...,
+      ["<C-i>"] = "select_default",
+      ...,
+
+  You can also add other mappings using tables with `type = "command"`.
     For example:
 
-    mappings = {
-      i = {
-        ["<esc>"] = require('telescope.actions').close,
-      },
-    }
+      ...,
+      ["jj"] = { "<esc>", type = "command" },
+      ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
+      ...,
+  ]]
+)
 
+append(
+  "default_mappings",
+  nil,
+  [[
+  Not recommended to use except for advanced users.
 
-    To disable a keymap, put [map] = false
-      So, to not map "<C-n>", just put
+  Will allow you to completely remove all of telescope's default maps
+  and use your own.
+  ]]
+)
 
-        ...,
-        ["<C-n>"] = false,
-        ...,
+append(
+  "file_sorter",
+  sorters.get_fzy_sorter,
+  [[
+  A function pointer that specifies the file_sorter. This sorter will
+  be used for find_files, git_files and similar.
+  Hint: If you load a native sorter, you dont need to change this value,
+  the native sorter will override it anyway.
 
-      Into your config.
+  Default: require("telescope.sorters").get_fzy_sorter]]
+)
 
+append(
+  "generic_sorter",
+  sorters.get_fzy_sorter,
+  [[
+  A function pointer to the generic sorter. The sorter that should be
+  used for everything that is not a file.
+  Hint: If you load a native sorter, you dont need to change this value,
+  the native sorter will override it anyway.
 
-    otherwise, just set the mapping to the function that you want it to
-    be.
+  Default: require("telescope.sorters").get_fzy_sorter]]
+)
 
-        ...,
-        ["<C-i>"] = require('telescope.actions').select_default,
-        ...,
+--TODO(conni2461): Why is this even configurable???
+append(
+  "prefilter_sorter",
+  sorters.prefilter,
+  [[
+  This points to a wrapper sorter around the generic_sorter that is able
+  to do prefiltering.
+  Its usually used for lsp_*_symbols and lsp_*_diagnostics
 
-    If the function you want is part of `telescope.actions`, then you can
-    simply give a string.
-      For example, the previous option is equivalent to:
+  Default: require("telescope.sorters").prefilter]]
+)
+
+append(
+  "file_ignore_patterns",
+  nil,
+  [[
+  A table of lua regex that define the files that should be ignored.
+  Example: { "^scratch/" } -- ignore all files in scratch directory
+  Example: { "%.npz" } -- ignore all npz files
+  See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more
+  information about lua regex
 
-        ...,
-        ["<C-i>"] = "select_default",
-        ...,
+  Default: nil]]
+)
 
-    You can also add other mappings using tables with `type = "command"`.
-      For example:
+append(
+  "file_previewer",
+  function(...)
+    return require("telescope.previewers").vim_buffer_cat.new(...)
+  end,
+  [[
+    Function pointer to the default file_previewer. It is mostly used
+    for find_files, git_files and similar.
+    You can change this function pointer to either use your own
+    previewer or use the command-line program bat as the previewer:
+      require("telescope.previewers").cat.new
 
-        ...,
-        ["jj"] = { "<esc>", type = "command" },
-        ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
-        ...,
-    ]],
-  },
+    Default: require("telescope.previewers").vim_buffer_cat.new]]
+)
 
-  default_mappings = {
-    nil,
-    [[
-    Not recommended to use except for advanced users.
+append(
+  "grep_previewer",
+  function(...)
+    return require("telescope.previewers").vim_buffer_vimgrep.new(...)
+  end,
+  [[
+    Function pointer to the default vim_grep previewer. It is mostly
+    used for live_grep, grep_string and similar.
+    You can change this function pointer to either use your own
+    previewer or use the command-line program bat as the previewer:
+      require("telescope.previewers").vimgrep.new
 
-    Will allow you to completely remove all of telescope's default maps
-    and use your own.
-    ]],
-  },
+    Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
+)
 
-  generic_sorter = { sorters.get_generic_fuzzy_sorter },
-  prefilter_sorter = { sorters.prefilter },
-  file_sorter = { sorters.get_fuzzy_file },
+append(
+  "qflist_previewer",
+  function(...)
+    return require("telescope.previewers").vim_buffer_qflist.new(...)
+  end,
+  [[
+    Function pointer to the default qflist previewer. It is mostly
+    used for qflist, loclist and lsp.
+    You can change this function pointer to either use your own
+    previewer or use the command-line program bat as the previewer:
+      require("telescope.previewers").qflist.new
 
-  file_ignore_patterns = { nil },
+    Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
+)
 
-  file_previewer = {
-    function(...)
-      return require("telescope.previewers").vim_buffer_cat.new(...)
-    end,
-  },
-  grep_previewer = {
-    function(...)
-      return require("telescope.previewers").vim_buffer_vimgrep.new(...)
-    end,
-  },
-  qflist_previewer = {
-    function(...)
-      return require("telescope.previewers").vim_buffer_qflist.new(...)
-    end,
-  },
-  buffer_previewer_maker = {
-    function(...)
-      return require("telescope.previewers").buffer_previewer_maker(...)
-    end,
-  },
-}
+append(
+  "buffer_previewer_maker",
+  function(...)
+    return require("telescope.previewers").buffer_previewer_maker(...)
+  end,
+  [[
+    Developer option that defines the underlining functionality
+    of the buffer previewer.
+    For interesting configuration examples take a look at
+    https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes
+
+    Default: require("telescope.previewers").buffer_previewer_maker]]
+)
 
 -- @param user_defaults table: a table where keys are the names of options,
 --    and values are the ones the user wants
@@ -470,8 +648,7 @@ function config.set_defaults(user_defaults, tele_defaults)
   end
 
   local function set(name, default_val, description)
-    -- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
-    -- assert(description, "Config values must always have a description")
+    assert(description, "Config values must always have a description")
 
     config.values[name] = get(name, default_val)
     if description then
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 7a740a3..d52d60d 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -2,6 +2,7 @@ local _extensions = require "telescope._extensions"
 
 local telescope = {}
 
+-- TODO(conni2461): also table of contents for tree-sitter-lua
 -- TODO: Add pre to the works
 -- ---@pre [[
 -- ---@pre ]]
@@ -10,22 +11,68 @@ local telescope = {}
 --- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
 --- filter, find and pick things in Lua.
 ---
+--- Getting started with telescope:
+---   1. Run `:checkhealth telescope` to make sure everything is installed.
+---   2. Evalulate it working with
+---      `:Telescope find_files` or
+---      `:lua require("telescope.builtin").find_files()`
+---   3. Put a `require("telescope").setup() call somewhere in your neovim config.
+---   4. Read |telescope.setup| to check what config keys are available and what you can put inside the setup call
+---   5. Read |telescope.builtin| to check which builtin pickers are offered and what options these implement
+---   6. Profit
+---
 --- <pre>
 --- To find out more:
 --- https://github.com/nvim-telescope/telescope.nvim
 ---
 ---   :h telescope.setup
+---   :h telescope.command
 ---   :h telescope.builtin
+---   :h telescope.themes
 ---   :h telescope.layout
+---   :h telescope.resolve
 ---   :h telescope.actions
+---   :h telescope.actions.state
+---   :h telescope.actions.set
+---   :h telescope.actions.utils
+---   :h telescope.actions.generate
+---   :h telescope.previewers
+---   :h telescope.actions.history
 --- </pre>
 ---@brief ]]
 
 ---@tag telescope.nvim
 
---- Setup function to be run by user. Configures the defaults, extensions
---- and other aspects of telescope.
----@param opts table: Configuration opts. Keys: defaults, extensions
+--- Setup function to be run by user. Configures the defaults, pickers and
+--- extensions of telescope.
+---
+--- Usage:
+--- <code>
+--- require('telescope').setup{
+---   defaults = {
+---     -- Default configuration for telescope goes here:
+---     -- config_key = value,
+---     -- ..
+---   },
+---   pickers = {
+---     -- Default configuration for builtin pickers goes here:
+---     -- picker_name = {
+---     --   picker_config_key = value,
+---     --   ...
+---     -- }
+---     -- Now the picker_config_key will be applied every time you call this
+---     -- builtin picker
+---   },
+---   extensions = {
+---     -- Your extension configuration goes here:
+---     -- extension_name = {
+---     --   extension_config_key = value,
+---     -- }
+---     -- please take a look at the readme of the extension you want to configure
+---   }
+--- }
+--- </code>
+---@param opts table: Configuration opts. Keys: defaults, pickers, extensions
 ---@eval { ["description"] = require('telescope').__format_setup_keys() }
 function telescope.setup(opts)
   opts = opts or {}
@@ -56,11 +103,9 @@ end
 telescope.extensions = require("telescope._extensions").manager
 
 telescope.__format_setup_keys = function()
+  local names = require("telescope.config").descriptions_order
   local descriptions = require("telescope.config").descriptions
 
-  local names = vim.tbl_keys(descriptions)
-  table.sort(names)
-
   local result = { "<pre>", "", "Valid keys for {opts.defaults}" }
   for _, name in ipairs(names) do
     local desc = descriptions[name]
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index beb7e18..bf0287c 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -61,7 +61,7 @@ do
   function make_entry.gen_from_file(opts)
     opts = opts or {}
 
-    local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+    local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
 
     local disable_devicons = opts.disable_devicons
 
@@ -181,7 +181,7 @@ do
     local display_string = "%s:%s%s"
 
     mt_vimgrep_entry = {
-      cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd()),
+      cwd = vim.fn.expand(opts.cwd or vim.loop.cwd()),
 
       display = function(entry)
         local display_filename = utils.transform_path(opts, entry.filename)
@@ -428,7 +428,7 @@ function make_entry.gen_from_buffer(opts)
     },
   }
 
-  local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+  local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
 
   local make_display = function(entry)
     local display_bufname = utils.transform_path(opts, entry.filename)
@@ -842,7 +842,7 @@ end
 function make_entry.gen_from_ctags(opts)
   opts = opts or {}
 
-  local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+  local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
   local current_file = Path:new(vim.fn.expand "%"):normalize(cwd)
 
   local display_items = {
diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index 1c0ce67..624ab00 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -538,14 +538,14 @@ end
 --- such as deleting buffers or files.
 ---
 --- Example usage:
---- <pre>
+--- <code>
 --- actions.delete_something = function(prompt_bufnr)
 ---    local current_picker = action_state.get_current_picker(prompt_bufnr)
 ---    current_picker:delete_selection(function(selection)
 ---      -- delete the selection outside of telescope
 ---    end)
 --- end
---- </pre>
+--- </code>
 ---
 --- Example usage in telescope:
 ---   - `actions.delete_buffer()`
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index b97888a..c703d4f 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -6,7 +6,7 @@
 ---
 --- All layout strategies are functions with the following signature:
 ---
---- <pre>
+--- <code>
 ---   function(picker, columns, lines, layout_config)
 ---     -- Do some calculations here...
 ---     return {
@@ -15,7 +15,9 @@
 ---       prompt = prompt_configuration,
 ---     }
 ---   end
+--- </code>
 ---
+--- <pre>
 ---   Parameters: ~
 ---     - picker        : A Picker object. (docs coming soon)
 ---     - columns       : (number) Columns in the vim window
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index b749056..0051fff 100644
--- a/lua/telescope/previewers/init.lua
+++ b/lua/telescope/previewers/init.lua
@@ -77,11 +77,11 @@ end
 --- It requires you to specify one table entry `get_command(entry, status)`.
 --- This `get_command` function has to return the terminal command that will be
 --- executed for each entry. Example:
---- <pre>
+--- <code>
 ---   get_command = function(entry, status)
 ---     return { 'bat', entry.path }
 ---   end
---- </pre>
+--- </code>
 ---
 --- Additionally you can define:
 --- - `title` a static title for example "File Preview"
@@ -219,12 +219,12 @@ previewers.qflist = term_previewer.qflist
 ---     - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
 ---   - If you want to use `vim.fn.search` or similar you need to run it in
 ---     that specific buffer context. Do
---- <pre>
+--- <code>
 ---       vim.api.nvim_buf_call(bufnr, function()
 ---         -- for example `search` and `matchadd`
 ---       end)
 ---     to achieve that.
---- </pre>
+--- </code>
 ---   - If you want to read a file into the buffer it's best to use
 ---     `buffer_previewer_maker`. But access this function with
 ---     `require('telescope.config').values.buffer_previewer_maker`
diff --git a/lua/telescope/themes.lua b/lua/telescope/themes.lua
index 1cd2efe..301fa37 100644
--- a/lua/telescope/themes.lua
+++ b/lua/telescope/themes.lua
@@ -15,14 +15,13 @@
 local themes = {}
 
 --- Dropdown style theme.
---- <pre>
 ---
 --- Usage:
----
+--- <code>
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.find_files(themes.get_dropdown())`
---- </pre>
+--- </code>
 function themes.get_dropdown(opts)
   opts = opts or {}
 
@@ -59,14 +58,14 @@ function themes.get_dropdown(opts)
 end
 
 --- Cursor style theme.
---- <pre>
 ---
 --- Usage:
+--- <code>
 ---
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.lsp_code_actions(themes.get_cursor())`
---- </pre>
+--- </code>
 function themes.get_cursor(opts)
   opts = opts or {}
 
@@ -97,14 +96,13 @@ function themes.get_cursor(opts)
 end
 
 --- Ivy style theme.
---- <pre>
 ---
 --- Usage:
----
+--- <code>
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.find_files(themes.get_ivy())`
---- </pre>
+--- </code>
 function themes.get_ivy(opts)
   opts = opts or {}