docs: start documenting previewers (#574)

Co-authored-by: Muhammed Zakir <MuhammedZakir@users.noreply.github.com>

5 files changed, 353 insertions, 73 deletions

diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index a625ac1..2d76c79 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -1,7 +1,7 @@
 ---@tag telescope.builtin
 
 ---@brief [[
---- A collection of builtin pickers for telesceope.
+--- A collection of builtin pickers for telescope.
 ---
 --- Meant for both example and for easy startup.
 ---
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index de6d544..5e025e3 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -12,6 +12,30 @@ local function first_non_null(...)
   end
 end
 
+local dedent = function(str, leave_indent)
+  -- find minimum common indent across lines
+  local indent = nil
+  for line in str:gmatch('[^\n]+') do
+    local line_indent = line:match('^%s+') or ''
+    if indent == nil or #line_indent < #indent then
+      indent = line_indent
+    end
+  end
+  if indent == nil or #indent == 0 then
+    -- no minimum common indent
+    return str
+  end
+  local left_indent = (' '):rep(leave_indent or 0)
+  -- create a pattern for the indent
+  indent = indent:gsub('%s', '[ \t]')
+  -- strip it from the first line
+  str = str:gsub('^'..indent, left_indent)
+  -- strip it from the remaining lines
+  str = str:gsub('[\n]'..indent, '\n' .. left_indent)
+  return str
+end
+
+
 local sorters = require('telescope.sorters')
 
 -- TODO: Add other major configuration points here.
@@ -35,33 +59,34 @@ function config.set_defaults(defaults)
 
     config.values[name] = get(name, default_val)
     if description then
-      config.descriptions[name] = vim.trim(description)
+      -- TODO(conni2461): trim is wrong. We need to do dedent here
+      config.descriptions[name] = dedent(vim.trim(description))
     end
   end
 
   set("sorting_strategy", "descending", [[
     Determines the direction "better" results are sorted towards.
 
-      Available options are:
-      - "descending" (default)
-      - "ascending"
+    Available options are:
+    - "descending" (default)
+    - "ascending"
   ]])
 
   set("selection_strategy", "reset", [[
     Determines how the cursor acts after each sort iteration.
 
-      Available options are:
-      - "reset" (default)
-      - "follow"
-      - "row"
+    Available options are:
+    - "reset" (default)
+    - "follow"
+    - "row"
   ]])
 
   set("scroll_strategy", "cycle", [[
     Determines what happens you try to scroll past view of the picker.
 
-      Available options are:
-      - "cycle" (default)
-      - "limit"
+    Available options are:
+    - "cycle" (default)
+    - "limit"
   ]])
 
   set("layout_strategy", "horizontal")
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index cca1a4c..7353755 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -12,6 +12,7 @@ local telescope = {}
 --- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
 --- filter, find and pick things in Lua.
 ---
+--- <pre>
 --- To find out more:
 --- https://github.com/nvim-telescope/telescope.nvim
 ---
@@ -19,6 +20,7 @@ local telescope = {}
 ---   :h telescope.builtin
 ---   :h telescope.layout
 ---   :h telescope.actions
+--- </pre>
 ---@brief ]]
 
 ---@tag telescope.nvim
@@ -50,7 +52,7 @@ function telescope.load_extension(name)
   return _extensions.load(name)
 end
 
---- Use telescope.extensions to reference any extensions within your configuration.
+--- Use telescope.extensions to reference any extensions within your configuration. <br>
 --- While the docs currently generate this as a function, it's actually a table. Sorry.
 telescope.extensions = require('telescope._extensions').manager
 
@@ -60,16 +62,19 @@ telescope.__format_setup_keys = function()
   local names = vim.tbl_keys(descriptions)
   table.sort(names)
 
-  local result = { "", "", "Valid keys for {opts.defaults}" }
+  local result = { "<pre>", "", "Valid keys for {opts.defaults}" }
   for _, name in ipairs(names) do
     local desc = descriptions[name]
 
     table.insert(result, "")
     table.insert(result, string.format("%s*telescope.defaults.%s*", string.rep(" ", 70 - 20 - #name), name))
     table.insert(result, string.format("%s: ~", name))
-    table.insert(result, string.format("    %s", desc))
+    for _, line in ipairs(vim.split(desc, '\n')) do
+      table.insert(result, string.format("    %s", line))
+    end
   end
 
+  table.insert(result, '</pre>')
   return result
 end
 
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index 16919de..691ee06 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -4,54 +4,55 @@
 ---
 --- Layout strategies are different functions to position telescope.
 ---
---- All layout strategies are functions with the following signature: >
+--- All layout strategies are functions with the following signature:
 ---
----      function(picker, columns, lines)
----        -- Do some calculations here...
----        return {
----          preview = preview_configuration
----          results = results_configuration,
----          prompt = prompt_configuration,
----        }
----      end
---- <
+--- <pre>
+---   function(picker, columns, lines)
+---     -- Do some calculations here...
+---     return {
+---       preview = preview_configuration
+---       results = results_configuration,
+---       prompt = prompt_configuration,
+---     }
+---   end
 ---
----     Parameters: ~
----         - picker  : A Picker object. (docs coming soon)
----         - columns : number Columns in the vim window
----         - lines   : number Lines in the vim window
+---   Parameters: ~
+---     - picker  : A Picker object. (docs coming soon)
+---     - columns : number Columns in the vim window
+---     - lines   : number Lines in the vim window
+---
+--- </pre>
 ---
 --- TODO: I would like to make these link to `telescope.layout_strategies.*`,
 --- but it's not yet possible.
 ---
 --- Available layout strategies include:
----   horizontal:
----   - See |layout_strategies.horizontal|
+---   - horizontal:
+---     - See |layout_strategies.horizontal|
 ---
----   vertical:
----   - See |layout_strategies.vertical|
+---   - vertical:
+---     - See |layout_strategies.vertical|
 ---
----   flex:
----   - See |layout_strategies.flex|
+---   - flex:
+---     - See |layout_strategies.flex|
 ---
 --- Available tweaks to the settings in layout defaults include
 --- (can be applied to horizontal and vertical layouts):
----   mirror (default is `false`):
----   - Flip the view of the current layout:
----     - If using horizontal: if `true`, swaps the location of the
----       results/prompt window and preview window
----     - If using vertical: if `true`, swaps the location of the results and
----       prompt windows
----
----   width_padding:
----   - How many cells to pad the width of Telescope's layout window
+---   - mirror (default is `false`):
+---     - Flip the view of the current layout:
+---       - If using horizontal: if `true`, swaps the location of the
+---         results/prompt window and preview window
+---       - If using vertical: if `true`, swaps the location of the results and
+---         prompt windows
 ---
----   height_padding:
----   - How many cells to pad the height of Telescope's layout window
+---   - width_padding:
+---     - How many cells to pad the width of Telescope's layout window
 ---
----   preview_width:
----   - Change the width of Telescope's preview window
+---   - height_padding:
+---     - How many cells to pad the height of Telescope's layout window
 ---
+---   - preview_width:
+---     - Change the width of Telescope's preview window
 ---@brief ]]
 
 local config = require('telescope.config')
@@ -82,6 +83,7 @@ local layout_strategies = {}
 
 --- Horizontal previewer
 ---
+--- <pre>
 ---   +-------------+--------------+
 ---   |             |              |
 ---   |   Results   |              |
@@ -90,6 +92,7 @@ local layout_strategies = {}
 ---   +-------------|              |
 ---   |   Prompt    |              |
 ---   +-------------+--------------+
+--- </pre>
 layout_strategies.horizontal = function(self, max_columns, max_lines)
   local layout_config = validate_layout_config(self.layout_config or {}, {
     width_padding = "How many cells to pad the width",
@@ -184,6 +187,7 @@ end
 
 --- Centered layout wih smaller default sizes (I think)
 ---
+--- <pre>
 ---    +--------------+
 ---    |    Preview   |
 ---    +--------------+
@@ -193,7 +197,7 @@ end
 ---    |    Result    |
 ---    |    Result    |
 ---    +--------------+
----
+--- </pre>
 layout_strategies.center = function(self, columns, lines)
   local initial_options = self:_get_initial_window_options()
   local preview = initial_options.preview
@@ -243,6 +247,7 @@ end
 
 --- Vertical perviewer stacks the items on top of each other.
 ---
+--- <pre>
 ---    +-----------------+
 ---    |    Previewer    |
 ---    |    Previewer    |
@@ -254,7 +259,7 @@ end
 ---    +-----------------+
 ---    |     Prompt      |
 ---    +-----------------+
----
+--- </pre>
 layout_strategies.vertical = function(self, max_columns, max_lines)
   local layout_config = validate_layout_config(self.layout_config or {}, {
     width_padding = "How many cells to pad the width",
@@ -326,11 +331,11 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
 end
 
 --- Swap between `horizontal` and `vertical` strategies based on the window width
----   -  Supports `vertical` or `horizontal` features
+---  -  Supports `vertical` or `horizontal` features
 ---
----   Uses:
----    flip_columns
----    flip_lines
+--- Uses:
+---  - flip_columns
+---  - flip_lines
 layout_strategies.flex = function(self, max_columns, max_lines)
   local layout_config = self.layout_config or {}
 
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index 286e483..be99c03 100644
--- a/lua/telescope/previewers/init.lua
+++ b/lua/telescope/previewers/init.lua
@@ -1,36 +1,281 @@
+---@tag telescope.previewers
+
+---@brief [[
+--- Provides a Previewer table that has to be implemented by each previewer.
+--- To achieve this, this module also provides two wrappers that abstract most
+--- of the work and make it really easy create new previewers.
+---   - `previewers.new_termopen_previewer`
+---   - `previewers.new_buffer_previewer`
+---
+--- Furthermore, there are a collection of previewers already defined which
+--- can be used for every picker, as long as the entries of the picker provide
+--- the necessary fields. The more important once are
+---   - `previewers.cat`
+---   - `previewers.vimgrep`
+---   - `previewers.qflist`
+---   - `previewers.vim_buffer_cat`
+---   - `previewers.vim_buffer_vimgrep`
+---   - `previewers.vim_buffer_qflist`
+---
+--- Previewers can be disabled for any builtin or custom picker by doing
+---   :Telescope find_files previewer=false
+---@brief ]]
+
 local Previewer = require('telescope.previewers.previewer')
 local term_previewer = require('telescope.previewers.term_previewer')
 local buffer_previewer = require('telescope.previewers.buffer_previewer')
 
 local previewers = {}
 
+--- This is the base table all previewers have to implement. It's possible to
+--- write a wrapper for this because most previewers need to have the same
+--- keys set.
+--- Examples of wrappers are:
+---   - `new_buffer_previewer`
+---   - `new_termopen_previewer`
+---
+--- To create a new table do following:
+---   - `local new_previewer = Previewer:new(opts)`
+---
+--- What `:new` expects is listed below
+---
+--- The interface provides following set of functions. All of them, besides
+--- `new`, will be handled by telescope pickers.
+--- - `:new(opts)`
+--- - `:preview(entry, status)`
+--- - `:teardown()`
+--- - `:send_input(input)`
+--- - `:scroll_fn(direction)`
+---
+--- `Previewer:new()` expects a table as input with following keys:
+---   - `setup` function(self): Will be called the first time preview will be
+---                           called.
+---   - `teardown` function(self): Will be called on cleanup.
+---   - `preview_fn` function(self, entry, status): Will be called each time
+---                                                 a new entry was selected.
+---   - `send_input` function(self, input): This is meant for
+---                                         `termopen_previewer` and it can be
+---                                         used to send input to the terminal
+---                                         application, like less.
+---   - `scroll_fn` function(self, direction): Used to make scrolling work.
+previewers.Previewer = Previewer
+
+--- A shorthand for creating a new Previewer.
+--- The provided table will be forwarded to `Previewer:new(...)`
 previewers.new = function(...)
   return Previewer:new(...)
 end
 
---- Deprecated previewers
+--- Is a wrapper around Previewer and helps with creating a new
+--- `termopen_previewer`.
+---
+--- 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:
+---   get_command = function(entry, status)
+---     return { 'bat', entry.path }
+---   end
+---
+--- It's an easy way to get your first previewer going and it integrates well
+--- with `bat` and `less`. Providing out of the box scrolling if the command
+--- uses less.
+---
+--- Furthermore, it will forward all `config.set_env` environment variables to
+--- that terminal process.
+---
+--- While this interface is a good start, it was replaced with the way more
+--- flexible `buffer_previewer` and is now deprecated.
 previewers.new_termopen_previewer = term_previewer.new_termopen_previewer
-previewers.cat                    = term_previewer.cat
-previewers.vimgrep                = term_previewer.vimgrep
-previewers.qflist                 = term_previewer.qflist
+
+
+--- Provides a `termopen_previewer` which has the ability to display files.
+--- It will always show the top of the file and has support for
+--- `bat`(prioritized) and `cat`. Each entry has to provide either the field
+--- `path` or `filename` in order to make this previewer work.
+---
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.cat_previewer`
+--- This will respect user configuration and will use `buffer_previewers` in
+--- case it's configured that way.
+previewers.cat = term_previewer.cat
+
+--- Provides a `termopen_previewer` which has the ability to display files at
+--- the provided line. It has support for `bat`(prioritized) and `cat`.
+--- Each entry has to provide either the field `path` or `filename` and
+--- a `lnum` field in order to make this previewer work.
+---
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.grep_previewer`
+--- This will respect user configuration and will use `buffer_previewers` in
+--- case it's configured that way.
+previewers.vimgrep = term_previewer.vimgrep
+
+--- Provides a `termopen_previewer` which has the ability to display files at
+--- the provided line or range. It has support for `bat`(prioritized) and
+--- `cat`. Each entry has to provide either the field `path` or `filename`,
+--- `lnum` and a `start` and `finish` range in order to make this previewer
+--- work.
+---
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.qflist_previewer`
+--- This will respect user configuration and will use buffer previewers in
+--- case it's configured that way.
+previewers.qflist = term_previewer.qflist
+
+
+--- An interface to instantiate a new `buffer_previewer`.
+--- That means that the content actually lives inside a vim buffer which
+--- enables us more control over the actual content. For example, we can
+--- use `vim.fn.search` to jump to a specific line or reuse buffers/already
+--- opened files more easily.
+--- This interface is more complex than `termopen_previewer` but offers more
+--- flexibility over your content.
+--- It was designed to display files but was extended to also display the
+--- output of terminal commands.
+---
+--- In the following options, state table and general tips are mentioned to
+--- make your experience with this previewer more seamless.
 ---
+---
+--- options:
+---   - `define_preview = function(self, entry, status)` (required)
+---     Is called for each selected entry, after each selection_move
+---     (up or down) and is meant to handle things like reading file,
+---     jump to line or attach a highlighter.
+---   - `setup = function(self)` (optional)
+---     Is called once at the beginning, before the preview for the first
+---     entry is displayed. You can return a table of vars that will be
+---     available in `self.state` in each `define_preview` call.
+---   - `teardown = function(self)` (optional)
+---     Will be called at the end, when the picker is being closed and is
+---     meant to cleanup everything that was allocated by the previewer.
+---     The `buffer_previewer` will automatically cleanup all created buffers.
+---     So you only need to handle things that were introduced by you.
+---   - `keep_last_buf = true` (optional)
+---     Will not delete the last selected buffer. This would allow you to
+---     reuse that buffer in the select action. For example, that buffer can
+---     be opened in a new split, rather than recreating that buffer in
+---     an action. To access the last buffer number:
+---     `require('telescope.state').get_global_key("last_preview_bufnr")`
+---   - `get_buffer_by_name = function(self, entry)`
+---     Allows you to set a unique name for each buffer. This is used for
+---     caching purpose. `self.state.bufname` will be nil if the entry was
+---     never loaded or the unique name when it was loaded once. For example,
+---     useful if you have one file but multiple entries. This happens for grep
+---     and lsp builtins. So to make the cache work only load content if
+---     `self.state.bufname ~= entry.your_unique_key`
+---
+--- `self.state` table:
+---   - `self.state.bufnr`
+---     Is the current buffer number, in which you have to write the loaded
+---     content.
+---     Don't create a buffer yourself, otherwise it's not managed by the
+---     buffer_previewer interface and you will probably be better off
+---     writing your own interface.
+---   - self.state.winid
+---     Current window id. Useful if you want to set the cursor to a provided
+---     line number.
+---   - self.state.bufname
+---     Will return the current buffer name, if `get_buffer_by_name` is
+---     defined. nil will be returned if the entry was never loaded or when
+---     `get_buffer_by_name` is not set.
+---
+--- Tips:
+---   - If you want to display content of a terminal job, use:
+---     `require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)`
+---       - `cmd` table: for example { 'git', 'diff', entry.value }
+---       - `bufnr` number: in which the content will be written
+---       - `opts` table: with following keys
+---         - `bufname` string: used for cache
+---         - `value` string: used for cache
+---         - `mode` string: either "insert" or "append". "insert" is default
+---         - `env` table: define environment variables. Example:
+---           - `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }`
+---         - `cwd` string: define current working directory for job
+---         - `callback` function(bufnr, content): will be called when job
+---           is done. Content will be nil if job is already loaded.
+---           So you can do highlighting only the first time the previewer
+---           is created for that entry.
+---           Use the returned `bufnr` and not `self.state.bufnr` in callback,
+---           because state can already be changed at this point in time.
+---   - If you want to attach a highlighter use:
+---     - `require('telescope.previewers.utils').highlighter(bufnr, ft)`
+---       - This will prioritize tree sitter highlighting if available for
+---         environment and language.
+---     - `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)`
+---     - `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>
+---       vim.api.nvim_buf_call(bufnr, function()
+---         -- for example `search` and `matchadd`
+---       end)
+---     to achieve that.
+--- </pre>
+---   - 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`
+---     because it can be redefined by users.
+previewers.new_buffer_previewer = buffer_previewer.new_buffer_previewer
 
-previewers.new_buffer_previewer   = buffer_previewer.new_buffer_previewer
+--- A universal way of reading a file into a buffer previewer.
+--- It handles async reading, cache, highlighting, displaying directories
+--- and provides a callback which can be used, to jump to a line in the buffer.
+---@param filepath string: String to the filepath, will be expanded
+---@param bufnr number: Where the content will be written
+---@param opts table: keys: `use_ft_detect`, `bufname` and `callback`
 previewers.buffer_previewer_maker = buffer_previewer.file_maker
-previewers.vim_buffer_cat         = buffer_previewer.cat
-previewers.vim_buffer_vimgrep     = buffer_previewer.vimgrep
-previewers.vim_buffer_qflist      = buffer_previewer.qflist
-previewers.git_branch_log         = buffer_previewer.git_branch_log
-previewers.git_commit_diff        = buffer_previewer.git_commit_diff
-previewers.git_file_diff          = buffer_previewer.git_file_diff
-previewers.ctags                  = buffer_previewer.ctags
-previewers.builtin                = buffer_previewer.builtin
-previewers.help                   = buffer_previewer.help
-previewers.man                    = buffer_previewer.man
-previewers.autocommands           = buffer_previewer.autocommands
-previewers.highlights             = buffer_previewer.highlights
-previewers.display_content        = buffer_previewer.display_content
 
-previewers.Previewer = Previewer
+
+--- A previewer that is used to display a file. It uses the `buffer_previewer`
+--- interface and won't jump to the line. To integrate this one into your
+--- own picker make sure that the field `path` or `filename` is set for
+--- each entry.
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.file_previewer`
+--- This will respect user configuration and will use `termopen_previewer` in
+--- case it's configured that way.
+previewers.vim_buffer_cat = buffer_previewer.cat
+
+--- A previewer that is used to display a file and jump to the provided line.
+--- It uses the `buffer_previewer` interface. To integrate this one into your
+--- own picker make sure that the field `path` or `filename` and `lnum` is set
+--- in each entry. If the latter is not present, it will default to the first
+--- line.
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.grep_previewer`
+--- This will respect user configuration and will use `termopen_previewer` in
+--- case it's configured that way.
+previewers.vim_buffer_vimgrep = buffer_previewer.vimgrep
+
+--- Is the same as `vim_buffer_vimgrep` and only exist for consistency with
+--- `term_previewers`.
+---
+--- The preferred way of using this previewer is like this
+--- `require('telescope.config').values.qflist_previewer`
+--- This will respect user configuration and will use `termopen_previewer` in
+--- case it's configured that way.
+previewers.vim_buffer_qflist = buffer_previewer.qflist
+
+
+previewers.git_branch_log = buffer_previewer.git_branch_log
+previewers.git_commit_diff = buffer_previewer.git_commit_diff
+previewers.git_file_diff = buffer_previewer.git_file_diff
+
+
+previewers.ctags = buffer_previewer.ctags
+previewers.builtin = buffer_previewer.builtin
+previewers.help = buffer_previewer.help
+previewers.man = buffer_previewer.man
+previewers.autocommands = buffer_previewer.autocommands
+previewers.highlights = buffer_previewer.highlights
+
+
+--- A deprecated way of displaying content more easily. Was written at a time,
+--- where the buffer_previewer interface wasn't present. Nowadays it's easier
+--- to just use this. We will keep it around for backwards compatibility
+--- because some extensions use it.
+--- It doesn't use cache or some other clever tricks.
+previewers.display_content = buffer_previewer.display_content
 
 return previewers