docs: document more actions and add introduction to actions (#1829)

2 files changed, 460 insertions, 64 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index e86e6ed..3bde535 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -1887,6 +1887,54 @@ resolver.resolve_anchor_pos()                  *resolver.resolve_anchor_pos()*
 
 Actions functions that are useful for people creating their own mappings.
 
+Actions can be either normal functions that expect the prompt_bufnr as first
+argument (1) or they can be a custom telescope type called "action" (2).
+
+(1) The `prompt_bufnr` of a normal function denotes the identifier of your
+picker which can be used to access the picker state. In practice, users most
+commonly access from both picker and global state via the following:
+
+>
+-- for utility functions
+local action_state = require "telescope.actions.state"
+
+local actions = {}
+actions.do_stuff = function(prompt_bufnr)
+  local current_picker = action_state.get_current_picker(prompt_bufnr) -- picker state
+  local entry = action_state.get_selected_entry()
+end
+<
+
+See |telescope.actions.state| for more information.
+
+(2) To transform a module of functions into a module of "action"s, you need to
+do the following:
+
+>
+local transform_mod = require("telescope.actions.mt").transform_mod
+
+local mod = {}
+mod.a1 = function(prompt_bufnr)
+  -- your code goes here
+  -- You can access the picker/global state as described above in (1).
+end
+
+mod.a2 = function(prompt_bufnr)
+  -- your code goes here
+end
+mod = transform_mod(mod)
+
+-- Now the following is possible. This means that actions a2 will be executed
+-- after action a1. You can chain as many actions as you want.
+local action = mod.a1 + mod.a2
+action(bufnr)
+<
+
+Another interesing thing to do is that these actions now have functions you can
+call. These functions include `:replace(f)`, `:replace_if(f, c)`,
+`replace_map(tbl)` and `enhance(tbl)`. More information on these functions can
+be found in the `developers.md` and `lua/tests/automated/action_spec.lua` file.
+
 actions.move_selection_next({prompt_bufnr})    *actions.move_selection_next()*
     Move the selection to the next entry
 
@@ -1995,6 +2043,47 @@ actions.toggle_all({prompt_bufnr})                      *actions.toggle_all()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.preview_scrolling_up({prompt_bufnr})  *actions.preview_scrolling_up()*
+    Scroll the preview window up
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.preview_scrolling_down({prompt_bufnr}) *actions.preview_scrolling_down()*
+    Scroll the preview window down
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.results_scrolling_up({prompt_bufnr})  *actions.results_scrolling_up()*
+    Scroll the results window up
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.results_scrolling_down({prompt_bufnr}) *actions.results_scrolling_down()*
+    Scroll the results window down
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.center({prompt_bufnr})                              *actions.center()*
+    Center the cursor in the window, can be used after selecting a file to edit
+    You can just map `actions.select_default + actions.center`
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.select_default({prompt_bufnr})              *actions.select_default()*
     Perform default action on selection, usually something like
     `:edit <selection>`
@@ -2039,6 +2128,124 @@ actions.select_tab({prompt_bufnr})                      *actions.select_tab()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.file_edit({prompt_bufnr})                        *actions.file_edit()*
+    Perform file edit on selection, usually something like
+    `:edit <selection>`
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.file_split({prompt_bufnr})                      *actions.file_split()*
+    Perform file split on selection, usually something like
+    `:new <selection>`
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.file_vsplit({prompt_bufnr})                    *actions.file_vsplit()*
+    Perform file vsplit on selection, usually something like
+    `:vnew <selection>`
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.file_tab({prompt_bufnr})                          *actions.file_tab()*
+    Perform file tab on selection, usually something like
+    `:tabedit <selection>`
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.close({prompt_bufnr})                                *actions.close()*
+    Close the Telescope window, usually used within an action
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions._close({prompt_bufnr}, {keepinsert})                *actions._close()*
+    Close the Telescope window and specify if you want to keep insert mode or
+    not
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)   The prompt bufnr
+        {keepinsert}   (boolean)  Remain in INSERT mode if true
+
+
+actions.edit_command_line({prompt_bufnr})        *actions.edit_command_line()*
+    Set a value in the command line and dont run it, making it editable.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.set_command_line({prompt_bufnr})          *actions.set_command_line()*
+    Set a value in the command line and run it
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.edit_search_line({prompt_bufnr})          *actions.edit_search_line()*
+    Set a value in the search line and dont search for it, making it editable.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.set_search_line({prompt_bufnr})            *actions.set_search_line()*
+    Set a value in the search line and search for it
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.edit_register({prompt_bufnr})                *actions.edit_register()*
+    Edit a register
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.paste_register({prompt_bufnr})              *actions.paste_register()*
+    Paste the selected register into the buffer
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.insert_symbol({prompt_bufnr})                *actions.insert_symbol()*
+    Insert a symbol into the current buffer (while switching to normal mode)
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.insert_symbol_i({prompt_bufnr})            *actions.insert_symbol_i()*
+    Insert a symbol into the current buffer and keeping the insert mode.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.git_create_branch({prompt_bufnr})        *actions.git_create_branch()*
     Create and checkout a new git branch if it doesn't already exist
 
@@ -2129,6 +2336,14 @@ actions.git_reset_hard({prompt_bufnr})              *actions.git_reset_hard()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.git_checkout_current_buffer({prompt_bufnr}) *actions.git_checkout_current_buffer()*
+    Checkout a specific file for a given sha
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 actions.git_staging_toggle({prompt_bufnr})      *actions.git_staging_toggle()*
     Stage/unstage selected file
 
@@ -2137,82 +2352,153 @@ actions.git_staging_toggle({prompt_bufnr})      *actions.git_staging_toggle()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
-actions.send_selected_to_qflist()          *actions.send_selected_to_qflist()*
+actions.send_selected_to_qflist({prompt_bufnr}) *actions.send_selected_to_qflist()*
     Sends the selected entries to the quickfix list, replacing the previous
     entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.add_selected_to_qflist()            *actions.add_selected_to_qflist()*
+actions.add_selected_to_qflist({prompt_bufnr}) *actions.add_selected_to_qflist()*
     Adds the selected entries to the quickfix list, keeping the previous
     entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.send_to_qflist()                            *actions.send_to_qflist()*
+actions.send_to_qflist({prompt_bufnr})              *actions.send_to_qflist()*
     Sends all entries to the quickfix list, replacing the previous entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.add_to_qflist()                              *actions.add_to_qflist()*
+actions.add_to_qflist({prompt_bufnr})                *actions.add_to_qflist()*
     Adds all entries to the quickfix list, keeping the previous entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.send_selected_to_loclist()        *actions.send_selected_to_loclist()*
+actions.send_selected_to_loclist({prompt_bufnr}) *actions.send_selected_to_loclist()*
     Sends the selected entries to the location list, replacing the previous
     entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.add_selected_to_loclist()          *actions.add_selected_to_loclist()*
+actions.add_selected_to_loclist({prompt_bufnr}) *actions.add_selected_to_loclist()*
     Adds the selected entries to the location list, keeping the previous
     entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.send_to_loclist()                          *actions.send_to_loclist()*
+actions.send_to_loclist({prompt_bufnr})            *actions.send_to_loclist()*
     Sends all entries to the location list, replacing the previous entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.add_to_loclist()                            *actions.add_to_loclist()*
+actions.add_to_loclist({prompt_bufnr})              *actions.add_to_loclist()*
     Adds all entries to the location list, keeping the previous entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.smart_send_to_qflist()                *actions.smart_send_to_qflist()*
+actions.smart_send_to_qflist({prompt_bufnr})  *actions.smart_send_to_qflist()*
     Sends the selected entries to the quickfix list, replacing the previous
     entries. If no entry was selected, sends all entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.smart_add_to_qflist()                  *actions.smart_add_to_qflist()*
+actions.smart_add_to_qflist({prompt_bufnr})    *actions.smart_add_to_qflist()*
     Adds the selected entries to the quickfix list, keeping the previous
     entries. If no entry was selected, adds all entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.smart_send_to_loclist()              *actions.smart_send_to_loclist()*
+actions.smart_send_to_loclist({prompt_bufnr}) *actions.smart_send_to_loclist()*
     Sends the selected entries to the location list, replacing the previous
     entries. If no entry was selected, sends all entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
 
-actions.smart_add_to_loclist()                *actions.smart_add_to_loclist()*
+actions.smart_add_to_loclist({prompt_bufnr})  *actions.smart_add_to_loclist()*
     Adds the selected entries to the location list, keeping the previous
     entries. If no entry was selected, adds all entries.
 
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.complete_tag({prompt_bufnr})                  *actions.complete_tag()*
+    Open completion menu containing the tags which can be used to filter the
+    results in a faster way
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.cycle_history_next({prompt_bufnr})      *actions.cycle_history_next()*
+    Cycle to the next search prompt in the history
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.cycle_history_prev({prompt_bufnr})      *actions.cycle_history_prev()*
+    Cycle to the previous search prompt in the history
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+actions.open_qflist({prompt_bufnr})                    *actions.open_qflist()*
+    Open the quickfix list. It makes sense to use this in combination with one
+    of the send_to_qflist actions `actions.smart_send_to_qflist +
+    actions.open_qflist`
+
 
-actions.open_qflist()                                  *actions.open_qflist()*
-    Open the quickfix list
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.open_loclist({prompt_bufnr})                  *actions.open_loclist()*
+    Open the location list. It makes sense to use this in combination with one
+    of the send_to_loclist actions `actions.smart_send_to_qflist +
+    actions.open_qflist`
 
-actions.open_loclist()                                *actions.open_loclist()*
-    Open the location list
 
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
 
 
 actions.delete_buffer({prompt_bufnr})                *actions.delete_buffer()*
diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index c69b368..2e16f1d 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -5,6 +5,55 @@
 
 ---@brief [[
 --- Actions functions that are useful for people creating their own mappings.
+---
+--- Actions can be either normal functions that expect the prompt_bufnr as
+--- first argument (1) or they can be a custom telescope type called "action" (2).
+---
+--- (1) The `prompt_bufnr` of a normal function denotes the identifier of your
+--- picker which can be used to access the picker state. In practice, users
+--- most commonly access from both picker and global state via the following:
+---
+--- <code>
+--- -- for utility functions
+--- local action_state = require "telescope.actions.state"
+---
+--- local actions = {}
+--- actions.do_stuff = function(prompt_bufnr)
+---   local current_picker = action_state.get_current_picker(prompt_bufnr) -- picker state
+---   local entry = action_state.get_selected_entry()
+--- end
+--- </code>
+---
+--- See |telescope.actions.state| for more information.
+---
+--- (2) To transform a module of functions into a module of "action"s, you need
+--- to do the following:
+---
+--- <code>
+--- local transform_mod = require("telescope.actions.mt").transform_mod
+---
+--- local mod = {}
+--- mod.a1 = function(prompt_bufnr)
+---   -- your code goes here
+---   -- You can access the picker/global state as described above in (1).
+--- end
+---
+--- mod.a2 = function(prompt_bufnr)
+---   -- your code goes here
+--- end
+--- mod = transform_mod(mod)
+---
+--- -- Now the following is possible. This means that actions a2 will be executed
+--- -- after action a1. You can chain as many actions as you want.
+--- local action = mod.a1 + mod.a2
+--- action(bufnr)
+--- </code>
+---
+--- Another interesing thing to do is that these actions now have functions you
+--- can call. These functions include `:replace(f)`, `:replace_if(f, c)`,
+--- `replace_map(tbl)` and `enhance(tbl)`. More information on these functions
+--- can be found in the `developers.md` and `lua/tests/automated/action_spec.lua`
+--- file.
 ---@brief ]]
 
 local a = vim.api
@@ -32,33 +81,33 @@ local actions = setmetatable({}, {
 
 --- Move the selection to the next entry
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_selection_next(prompt_bufnr)
+actions.move_selection_next = function(prompt_bufnr)
   action_set.shift_selection(prompt_bufnr, 1)
 end
 
 --- Move the selection to the previous entry
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_selection_previous(prompt_bufnr)
+actions.move_selection_previous = function(prompt_bufnr)
   action_set.shift_selection(prompt_bufnr, -1)
 end
 
 --- Move the selection to the entry that has a worse score
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_selection_worse(prompt_bufnr)
+actions.move_selection_worse = function(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
   action_set.shift_selection(prompt_bufnr, p_scroller.worse(picker.sorting_strategy))
 end
 
 --- Move the selection to the entry that has a better score
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_selection_better(prompt_bufnr)
+actions.move_selection_better = function(prompt_bufnr)
   local picker = action_state.get_current_picker(prompt_bufnr)
   action_set.shift_selection(prompt_bufnr, p_scroller.better(picker.sorting_strategy))
 end
 
 --- Move to the top of the picker
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_to_top(prompt_bufnr)
+actions.move_to_top = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:set_selection(
     p_scroller.top(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -67,7 +116,7 @@ end
 
 --- Move to the middle of the picker
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_to_middle(prompt_bufnr)
+actions.move_to_middle = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:set_selection(
     p_scroller.middle(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -76,7 +125,7 @@ end
 
 --- Move to the bottom of the picker
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.move_to_bottom(prompt_bufnr)
+actions.move_to_bottom = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:set_selection(
     p_scroller.bottom(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -85,21 +134,21 @@ end
 
 --- Add current entry to multi select
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.add_selection(prompt_bufnr)
+actions.add_selection = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:add_selection(current_picker:get_selection_row())
 end
 
 --- Remove current entry from multi select
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.remove_selection(prompt_bufnr)
+actions.remove_selection = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:remove_selection(current_picker:get_selection_row())
 end
 
 --- Toggle current entry status for multi select
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.toggle_selection(prompt_bufnr)
+actions.toggle_selection = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   current_picker:toggle_selection(current_picker:get_selection_row())
 end
@@ -107,7 +156,7 @@ end
 --- Multi select all entries.
 --- - Note: selected entries may include results not visible in the results popup.
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.select_all(prompt_bufnr)
+actions.select_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   action_utils.map_entries(prompt_bufnr, function(entry, _, row)
     if not current_picker._multi:is_selected(entry) then
@@ -126,7 +175,7 @@ end
 
 --- Drop all entries from the current multi selection.
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.drop_all(prompt_bufnr)
+actions.drop_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   action_utils.map_entries(prompt_bufnr, function(entry, _, row)
     current_picker._multi:drop(entry)
@@ -144,7 +193,7 @@ end
 --- Toggle multi selection for all entries.
 --- - Note: toggled entries may include results not visible in the results popup.
 ---@param prompt_bufnr number: The prompt bufnr
-function actions.toggle_all(prompt_bufnr)
+actions.toggle_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   action_utils.map_entries(prompt_bufnr, function(entry, _, row)
     current_picker._multi:toggle(entry)
@@ -159,23 +208,34 @@ function actions.toggle_all(prompt_bufnr)
   current_picker:get_status_updater(current_picker.prompt_win, current_picker.prompt_bufnr)()
 end
 
-function actions.preview_scrolling_up(prompt_bufnr)
+--- Scroll the preview window up
+---@param prompt_bufnr number: The prompt bufnr
+actions.preview_scrolling_up = function(prompt_bufnr)
   action_set.scroll_previewer(prompt_bufnr, -1)
 end
 
-function actions.preview_scrolling_down(prompt_bufnr)
+--- Scroll the preview window down
+---@param prompt_bufnr number: The prompt bufnr
+actions.preview_scrolling_down = function(prompt_bufnr)
   action_set.scroll_previewer(prompt_bufnr, 1)
 end
 
-function actions.results_scrolling_up(prompt_bufnr)
+--- Scroll the results window up
+---@param prompt_bufnr number: The prompt bufnr
+actions.results_scrolling_up = function(prompt_bufnr)
   action_set.scroll_results(prompt_bufnr, -1)
 end
 
-function actions.results_scrolling_down(prompt_bufnr)
+--- Scroll the results window down
+---@param prompt_bufnr number: The prompt bufnr
+actions.results_scrolling_down = function(prompt_bufnr)
   action_set.scroll_results(prompt_bufnr, 1)
 end
 
-function actions.center(_)
+--- Center the cursor in the window, can be used after selecting a file to edit
+--- You can just map `actions.select_default + actions.center`
+---@param prompt_bufnr number: The prompt bufnr
+actions.center = function(prompt_bufnr)
   vim.cmd ":normal! zz"
 end
 
@@ -250,28 +310,49 @@ actions.select_tab = {
 -- TODO: consider adding float!
 -- https://github.com/nvim-telescope/telescope.nvim/issues/365
 
-function actions.file_edit(prompt_bufnr)
+--- Perform file edit on selection, usually something like<br>
+--- `:edit <selection>`
+---@param prompt_bufnr number: The prompt bufnr
+actions.file_edit = function(prompt_bufnr)
   return action_set.edit(prompt_bufnr, "edit")
 end
 
-function actions.file_split(prompt_bufnr)
+--- Perform file split on selection, usually something like<br>
+--- `:new <selection>`
+---@param prompt_bufnr number: The prompt bufnr
+actions.file_split = function(prompt_bufnr)
   return action_set.edit(prompt_bufnr, "new")
 end
 
-function actions.file_vsplit(prompt_bufnr)
+--- Perform file vsplit on selection, usually something like<br>
+--- `:vnew <selection>`
+---@param prompt_bufnr number: The prompt bufnr
+actions.file_vsplit = function(prompt_bufnr)
   return action_set.edit(prompt_bufnr, "vnew")
 end
 
-function actions.file_tab(prompt_bufnr)
+--- Perform file tab on selection, usually something like<br>
+--- `:tabedit <selection>`
+---@param prompt_bufnr number: The prompt bufnr
+actions.file_tab = function(prompt_bufnr)
   return action_set.edit(prompt_bufnr, "tabedit")
 end
 
-function actions.close_pum(_)
+actions.close_pum = function(_)
   if 0 ~= vim.fn.pumvisible() then
     vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes("<c-y>", true, true, true), "n", true)
   end
 end
 
+--- Close the Telescope window, usually used within an action
+---@param prompt_bufnr number: The prompt bufnr
+actions.close = function(prompt_bufnr)
+  actions._close(prompt_bufnr, false)
+end
+
+--- Close the Telescope window and specify if you want to keep insert mode or not
+---@param prompt_bufnr number: The prompt bufnr
+---@param keepinsert boolean: Remain in INSERT mode if true
 actions._close = function(prompt_bufnr, keepinsert)
   action_state.get_current_history():reset()
   local picker = action_state.get_current_picker(prompt_bufnr)
@@ -288,20 +369,25 @@ actions._close = function(prompt_bufnr, keepinsert)
   pcall(a.nvim_set_current_win, original_win_id)
 end
 
-function actions.close(prompt_bufnr)
-  actions._close(prompt_bufnr, false)
-end
-
-actions.edit_command_line = function(prompt_bufnr)
+local set_edit_line = function(prompt_bufnr, fname, prefix, postfix)
+  postfix = vim.F.if_nil(postfix, "")
   local selection = action_state.get_selected_entry()
   if selection == nil then
-    utils.__warn_no_selection "actions.edit_command_line"
+    utils.__warn_no_selection(fname)
     return
   end
   actions.close(prompt_bufnr)
-  a.nvim_feedkeys(a.nvim_replace_termcodes(":" .. selection.value, true, false, true), "t", true)
+  a.nvim_feedkeys(a.nvim_replace_termcodes(prefix .. selection.value .. postfix, true, false, true), "t", true)
+end
+
+--- Set a value in the command line and dont run it, making it editable.
+---@param prompt_bufnr number: The prompt bufnr
+actions.edit_command_line = function(prompt_bufnr)
+  set_edit_line(prompt_bufnr, "actions.edit_command_line", ":")
 end
 
+--- Set a value in the command line and run it
+---@param prompt_bufnr number: The prompt bufnr
 actions.set_command_line = function(prompt_bufnr)
   local selection = action_state.get_selected_entry()
   if selection == nil then
@@ -313,26 +399,20 @@ actions.set_command_line = function(prompt_bufnr)
   vim.cmd(selection.value)
 end
 
+--- Set a value in the search line and dont search for it, making it editable.
+---@param prompt_bufnr number: The prompt bufnr
 actions.edit_search_line = function(prompt_bufnr)
-  local selection = action_state.get_selected_entry()
-  if selection == nil then
-    utils.__warn_no_selection "actions.edit_search_line"
-    return
-  end
-  actions.close(prompt_bufnr)
-  a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. selection.value, true, false, true), "t", true)
+  set_edit_line(prompt_bufnr, "actions.edit_search_line", "/")
 end
 
+--- Set a value in the search line and search for it
+---@param prompt_bufnr number: The prompt bufnr
 actions.set_search_line = function(prompt_bufnr)
-  local selection = action_state.get_selected_entry()
-  if selection == nil then
-    utils.__warn_no_selection "actions.set_search_line"
-    return
-  end
-  actions.close(prompt_bufnr)
-  a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. selection.value .. "<CR>", true, false, true), "t", true)
+  set_edit_line(prompt_bufnr, "actions.set_search_line", "/", "<CR>")
 end
 
+--- Edit a register
+---@param prompt_bufnr number: The prompt bufnr
 actions.edit_register = function(prompt_bufnr)
   local selection = action_state.get_selected_entry()
   local picker = action_state.get_current_picker(prompt_bufnr)
@@ -355,6 +435,8 @@ actions.edit_register = function(prompt_bufnr)
   -- print(vim.inspect(picker.finder.results))
 end
 
+--- Paste the selected register into the buffer
+---@param prompt_bufnr number: The prompt bufnr
 actions.paste_register = function(prompt_bufnr)
   local selection = action_state.get_selected_entry()
   if selection == nil then
@@ -370,12 +452,16 @@ actions.paste_register = function(prompt_bufnr)
   end
 end
 
+--- Insert a symbol into the current buffer (while switching to normal mode)
+---@param prompt_bufnr number: The prompt bufnr
 actions.insert_symbol = function(prompt_bufnr)
   local symbol = action_state.get_selected_entry().value[1]
   actions.close(prompt_bufnr)
   vim.api.nvim_put({ symbol }, "", true, true)
 end
 
+--- Insert a symbol into the current buffer and keeping the insert mode.
+---@param prompt_bufnr number: The prompt bufnr
 actions.insert_symbol_i = function(prompt_bufnr)
   local symbol = action_state.get_selected_entry().value[1]
   actions._close(prompt_bufnr, true)
@@ -658,6 +744,8 @@ actions.git_reset_hard = function(prompt_bufnr)
   git_reset_branch(prompt_bufnr, "--hard")
 end
 
+--- Checkout a specific file for a given sha
+---@param prompt_bufnr number: The prompt bufnr
 actions.git_checkout_current_buffer = function(prompt_bufnr)
   local cwd = action_state.get_current_picker(prompt_bufnr).cwd
   local selection = action_state.get_selected_entry()
@@ -742,41 +830,49 @@ local send_all_to_qf = function(prompt_bufnr, mode, target)
 end
 
 --- Sends the selected entries to the quickfix list, replacing the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.send_selected_to_qflist = function(prompt_bufnr)
   send_selected_to_qf(prompt_bufnr, " ")
 end
 
 --- Adds the selected entries to the quickfix list, keeping the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.add_selected_to_qflist = function(prompt_bufnr)
   send_selected_to_qf(prompt_bufnr, "a")
 end
 
 --- Sends all entries to the quickfix list, replacing the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.send_to_qflist = function(prompt_bufnr)
   send_all_to_qf(prompt_bufnr, " ")
 end
 
 --- Adds all entries to the quickfix list, keeping the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.add_to_qflist = function(prompt_bufnr)
   send_all_to_qf(prompt_bufnr, "a")
 end
 
 --- Sends the selected entries to the location list, replacing the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.send_selected_to_loclist = function(prompt_bufnr)
   send_selected_to_qf(prompt_bufnr, " ", "loclist")
 end
 
 --- Adds the selected entries to the location list, keeping the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.add_selected_to_loclist = function(prompt_bufnr)
   send_selected_to_qf(prompt_bufnr, "a", "loclist")
 end
 
 --- Sends all entries to the location list, replacing the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.send_to_loclist = function(prompt_bufnr)
   send_all_to_qf(prompt_bufnr, " ", "loclist")
 end
 
 --- Adds all entries to the location list, keeping the previous entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.add_to_loclist = function(prompt_bufnr)
   send_all_to_qf(prompt_bufnr, "a", "loclist")
 end
@@ -792,28 +888,34 @@ end
 
 --- Sends the selected entries to the quickfix list, replacing the previous entries.
 --- If no entry was selected, sends all entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.smart_send_to_qflist = function(prompt_bufnr)
   smart_send(prompt_bufnr, " ")
 end
 
 --- Adds the selected entries to the quickfix list, keeping the previous entries.
 --- If no entry was selected, adds all entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.smart_add_to_qflist = function(prompt_bufnr)
   smart_send(prompt_bufnr, "a")
 end
 
 --- Sends the selected entries to the location list, replacing the previous entries.
 --- If no entry was selected, sends all entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.smart_send_to_loclist = function(prompt_bufnr)
   smart_send(prompt_bufnr, " ", "loclist")
 end
 
 --- Adds the selected entries to the location list, keeping the previous entries.
 --- If no entry was selected, adds all entries.
+---@param prompt_bufnr number: The prompt bufnr
 actions.smart_add_to_loclist = function(prompt_bufnr)
   smart_send(prompt_bufnr, "a", "loclist")
 end
 
+--- Open completion menu containing the tags which can be used to filter the results in a faster way
+---@param prompt_bufnr number: The prompt bufnr
 actions.complete_tag = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
   local tags = current_picker.sorter.tags
@@ -863,6 +965,8 @@ actions.complete_tag = function(prompt_bufnr)
   vim.fn.complete(col - #line, filtered_tags)
 end
 
+--- Cycle to the next search prompt in the history
+---@param prompt_bufnr number: The prompt bufnr
 actions.cycle_history_next = function(prompt_bufnr)
   local history = action_state.get_current_history()
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -879,6 +983,8 @@ actions.cycle_history_next = function(prompt_bufnr)
   end
 end
 
+--- Cycle to the previous search prompt in the history
+---@param prompt_bufnr number: The prompt bufnr
 actions.cycle_history_prev = function(prompt_bufnr)
   local history = action_state.get_current_history()
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -894,13 +1000,17 @@ actions.cycle_history_prev = function(prompt_bufnr)
   end
 end
 
---- Open the quickfix list
-actions.open_qflist = function(_)
+--- Open the quickfix list. It makes sense to use this in combination with one of the send_to_qflist actions
+--- `actions.smart_send_to_qflist + actions.open_qflist`
+---@param prompt_bufnr number: The prompt bufnr
+actions.open_qflist = function(prompt_bufnr)
   vim.cmd [[copen]]
 end
 
---- Open the location list
-actions.open_loclist = function(_)
+--- Open the location list. It makes sense to use this in combination with one of the send_to_loclist actions
+--- `actions.smart_send_to_qflist + actions.open_qflist`
+---@param prompt_bufnr number: The prompt bufnr
+actions.open_loclist = function(prompt_bufnr)
   vim.cmd [[lopen]]
 end