docs: add other actions modules (#792)

* docs: add other actions modules

* [docgen] Update doc/telescope.txt
skip-checks: true

* fixup

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Github Actions <actions@github>

doc/telescope.txt

@@ -92,22 +92,54 @@ telescope.extensions()                                *telescope.extensions()*
 
 
 ================================================================================
-                                                             *telescope.builtin*
+                                                         *telescope.actions.set*
 
-A collection of builtin pickers for telescope.
+Telescope action sets are used to provide an interface for managing actions
+that all primarily do the same thing, but with slight tweaks.
 
-Meant for both example and for easy startup.
+For example, when editing files you may want it in the current split, a
+vertical split, etc. Instead of making users have to overwrite EACH of those
+every time they want to change this behavior, they can instead replace the
+`set` itself and then it will work great and they're done.
 
-Any of these functions can just be called directly by doing:
+action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()*
+    Move the current selection of a picker {change} rows. Handles not
+    overflowing / underflowing the list.
 
-:lua require('telescope.builtin').$NAME()
 
-This will use the default configuration options. Other configuration options
+    Parameters: ~
-are still in flux at the moment
+        {prompt_bufnr} (number)  The prompt bufnr
+        {change}       (number)  The amount to shift the selection by
 
-builtin.live_grep()                                      *builtin.live_grep()*
-    Live grep means grep as you type.
 
+action_set.select({prompt_bufnr}, {type})                *action_set.select()*
+    Select the current entry. This is the action set to overwrite common
+    actions by the user.
+
+    By default maps to editing a file.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {type}         (string)  The type of selection to make
+
+
+action_set.edit({prompt_bufnr}, {command})                 *action_set.edit()*
+    Edit a file based on the current selection.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {command}      (string)  The command to use to open the file.
+
+
+action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()*
+    Scrolls the previewer up or down
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+        {direction}    (number)  The direction of the scrolling
 
 
 
@@ -234,6 +266,52 @@ actions.open_qflist()                                  *actions.open_qflist()*
 
 
 
+================================================================================
+                                                             *telescope.builtin*
+
+A collection of builtin pickers for telescope.
+
+Meant for both example and for easy startup.
+
+Any of these functions can just be called directly by doing:
+
+:lua require('telescope.builtin').$NAME()
+
+This will use the default configuration options. Other configuration options
+are still in flux at the moment
+
+builtin.live_grep()                                      *builtin.live_grep()*
+    Live grep means grep as you type.
+
+
+
+
+================================================================================
+                                                       *telescope.actions.state*
+
+Functions to be used to determine the current state of telescope.
+
+Generally used from within other |telescope.actions|
+
+action_state.get_selected_entry()          *action_state.get_selected_entry()*
+    Get the current entry
+
+
+
+action_state.get_current_line()              *action_state.get_current_line()*
+    Gets the current line
+
+
+
+action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()*
+    Gets the current picker
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
+
 ================================================================================
                                                           *telescope.previewers*
 

lua/telescope/actions/set.lua

@@ -1,3 +1,15 @@
+---@tag telescope.actions.set
+
+---@brief [[
+--- Telescope action sets are used to provide an interface for managing
+--- actions that all primarily do the same thing, but with slight tweaks.
+---
+--- For example, when editing files you may want it in the current split,
+--- a vertical split, etc. Instead of making users have to overwrite EACH
+--- of those every time they want to change this behavior, they can instead
+--- replace the `set` itself and then it will work great and they're done.
+---@brief ]]
+
 local a = vim.api
 
 local log = require('telescope.log')
@@ -8,14 +20,7 @@ local action_state = require('telescope.actions.state')
 
 local transform_mod = require('telescope.actions.mt').transform_mod
 
---- Telescope action sets are used to provide an interface for managing
+local action_set = setmetatable({}, {
---- actions that all primarily do the same thing, but with slight tweaks.
----
---- For example, when editing files you may want it in the current split,
---- a vertical split, etc. Instead of making users have to overwrite EACH
---- of those every time they want to change this behavior, they can instead
---- replace the `set` itself and then it will work great and they're done.
-local set = setmetatable({}, {
   __index = function(_, k)
     error("'telescope.actions.set' does not have a value: " .. tostring(k))
   end
@@ -25,7 +30,7 @@ local set = setmetatable({}, {
 --- Handles not overflowing / underflowing the list.
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param change number: The amount to shift the selection by
-set.shift_selection = function(prompt_bufnr, change)
+action_set.shift_selection = function(prompt_bufnr, change)
   local count = vim.v.count
   count = count == 0 and 1 or count
   count = a.nvim_get_mode().mode == "n" and count or 1
@@ -39,8 +44,8 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param type string: The type of selection to make
 --          Valid types include: "default", "horizontal", "vertical", "tabedit"
-set.select = function(prompt_bufnr, type)
+action_set.select = function(prompt_bufnr, type)
-  return set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type))
+  return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type))
 end
 
 local edit_buffer
@@ -65,7 +70,7 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param command string: The command to use to open the file.
 --      Valid commands include: "edit", "new", "vedit", "tabedit"
-set.edit = function(prompt_bufnr, command)
+action_set.edit = function(prompt_bufnr, command)
   local entry = action_state.get_selected_entry()
 
   if not entry then
@@ -129,7 +134,7 @@ end
 ---@param prompt_bufnr number: The prompt bufnr
 ---@param direction number: The direction of the scrolling
 --      Valid directions include: "1", "-1"
-set.scroll_previewer = function (prompt_bufnr, direction)
+action_set.scroll_previewer = function (prompt_bufnr, direction)
   local status = state.get_status(prompt_bufnr)
   local default_speed = vim.api.nvim_win_get_height(status.preview_win) / 2
   local speed = status.picker.layout_config.scroll_speed or default_speed
@@ -140,5 +145,5 @@ end
 -- ==================================================
 -- Transforms modules and sets the corect metatables.
 -- ==================================================
-set = transform_mod(set)
+action_set = transform_mod(action_set)
-return set
+return action_set

lua/telescope/actions/state.lua

@@ -1,3 +1,11 @@
+---@tag telescope.actions.state
+
+---@brief [[
+--- Functions to be used to determine the current state of telescope.
+---
+--- Generally used from within other |telescope.actions|
+---@brief ]]
+
 local global_state = require('telescope.state')
 
 local action_state = {}
@@ -13,6 +21,7 @@ function action_state.get_current_line()
 end
 
 --- Gets the current picker
+---@param prompt_bufnr number: The prompt bufnr
 function action_state.get_current_picker(prompt_bufnr)
   return global_state.get_status(prompt_bufnr).picker
 end

scripts/gendocs.lua

@@ -12,6 +12,8 @@ docs.test = function()
     "./lua/telescope/builtin/init.lua",
     "./lua/telescope/pickers/layout_strategies.lua",
     "./lua/telescope/actions/init.lua",
+    "./lua/telescope/actions/state.lua",
+    "./lua/telescope/actions/set.lua",
     "./lua/telescope/previewers/init.lua",
   }