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

2021-09-13 22:03:41 +02:00
parent aaffa84ebb
commit 5131df7df1
17 changed files with 1822 additions and 1165 deletions
--- 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