docs: proof-read edits (#2311)

lua/telescope/actions/init.lua

@@ -2,9 +2,9 @@
 ---@config { ["module"] = "telescope.actions" }
 
 ---@brief [[
---- Actions functions that are useful for people creating their own mappings.
+--- These functions are useful for people creating their own mappings.
 ---
---- Actions can be either normal functions that expect the prompt_bufnr as
+--- 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
@@ -45,7 +45,7 @@
 ---   action(bufnr)
 --- </code>
 ---
---- Another interesing thing to do is that these actions now have functions you
+--- Another interesting 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`
@@ -150,7 +150,7 @@ actions.toggle_selection = function(prompt_bufnr)
 end
 
 --- Multi select all entries.
---- - Note: selected entries may include results not visible in the results popup.
+--- - Note: selected entries may include results not visible in the results pop up.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.select_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -187,7 +187,7 @@ actions.drop_all = function(prompt_bufnr)
 end
 
 --- Toggle multi selection for all entries.
---- - Note: toggled entries may include results not visible in the results popup.
+--- - Note: toggled entries may include results not visible in the results pop up.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.toggle_all = function(prompt_bufnr)
   local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -403,7 +403,7 @@ local set_edit_line = function(prompt_bufnr, fname, prefix, postfix)
   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.
+--- Set a value in the command line and don't 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", ":")
@@ -422,7 +422,7 @@ 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.
+--- Set a value in the search line and don't search for it, making it editable.
 ---@param prompt_bufnr number: The prompt bufnr
 actions.edit_search_line = function(prompt_bufnr)
   set_edit_line(prompt_bufnr, "actions.edit_search_line", "/")

lua/telescope/actions/utils.lua

@@ -13,7 +13,7 @@ local utils = {}
 
 --- Apply `f` to the entries of the current picker.
 --- - Notes:
----   - Mapped entries include all currently filtered results, not just the visible onces.
+---   - Mapped entries include all currently filtered results, not just the visible ones.
 ---   - Indices are 1-indexed, whereas rows are 0-indexed.
 --- - Warning: `map_entries` has no return value.
 ---   - The below example showcases how to collect results
@@ -26,7 +26,7 @@ local utils = {}
 ---     local prompt_bufnr = vim.api.nvim_get_current_buf()
 ---     local current_picker = action_state.get_current_picker(prompt_bufnr)
 ---     local results = {}
----       action_utils.map_entries(prompt_bufnr, function(entry, index, row)
+---     action_utils.map_entries(prompt_bufnr, function(entry, index, row)
 ---       results[row] = entry.value
 ---     end)
 ---     return results
@@ -50,7 +50,7 @@ end
 
 --- Apply `f` to the multi selections of the current picker and return a table of mapped selections.
 --- - Notes:
----   - Mapped selections may include results not visible in the results popup.
+---   - Mapped selections may include results not visible in the results pop up.
 ---   - Selected entries are returned in order of their selection.
 --- - Warning: `map_selections` has no return value.
 ---   - The below example showcases how to collect results
@@ -63,7 +63,7 @@ end
 ---     local prompt_bufnr = vim.api.nvim_get_current_buf()
 ---     local current_picker = action_state.get_current_picker(prompt_bufnr)
 ---     local results = {}
----       action_utils.map_selections(prompt_bufnr, function(entry, index)
+---     action_utils.map_selections(prompt_bufnr, function(entry, index)
 ---       results[index] = entry.value
 ---     end)
 ---     return results

lua/telescope/builtin/init.lua

@@ -96,7 +96,7 @@ builtin.treesitter = require_on_exported_call("telescope.builtin.__files").trees
 
 --- 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)
+---@field skip_empty_lines boolean: if true we don't 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
@@ -133,7 +133,7 @@ builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.__file
 ---@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: false)
 ---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default: false)
----@field git_command table: command that will be exectued. {"git","ls-files","--exclude-standard","--cached"}
+---@field git_command table: command that will be executed. {"git","ls-files","--exclude-standard","--cached"}
 builtin.git_files = require_on_exported_call("telescope.builtin.__git").files
 
 --- Lists commits for current directory with diff preview
@@ -145,11 +145,11 @@ builtin.git_files = require_on_exported_call("telescope.builtin.__git").files
 ---@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_command table: command that will be exectued. {"git","log","--pretty=oneline","--abbrev-commit","--","."}
+---@field git_command table: command that will be executed. {"git","log","--pretty=oneline","--abbrev-commit","--","."}
 builtin.git_commits = require_on_exported_call("telescope.builtin.__git").commits
 
 --- Lists commits for current buffer with diff preview
---- - Default keymaps or your overriden `select_` keys:
+--- - Default keymaps or your overridden `select_` keys:
 ---   - `<cr>`: checks out the currently selected commit
 ---   - `<c-v>`: opens a diff in a vertical split
 ---   - `<c-x>`: opens a diff in a horizontal split
@@ -158,7 +158,7 @@ builtin.git_commits = require_on_exported_call("telescope.builtin.__git").commit
 ---@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)
----@field git_command table: command that will be exectued. {"git","log","--pretty=oneline","--abbrev-commit"}
+---@field git_command table: command that will be executed. {"git","log","--pretty=oneline","--abbrev-commit"}
 builtin.git_bcommits = require_on_exported_call("telescope.builtin.__git").bcommits
 
 --- List branches for current directory, with output from `git log --oneline` shown in the preview window
@@ -224,8 +224,8 @@ builtin.pickers = require_on_exported_call("telescope.builtin.__internal").picke
 
 --- 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)
----@field show_moon boolean: we love the moon (default: false, because its a hidden feature)
+---@field show_pluto boolean: we love Pluto (default: false, because its a hidden feature)
+---@field show_moon boolean: we love the Moon (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

lua/telescope/config.lua

@@ -198,9 +198,9 @@ append(
   and `actions.layout.cycle_layout_prev`.
   Should be a list of "layout setups".
   Each "layout setup" can take one of two forms:
-  1. string <br>
+  1. string
       This is interpreted as the name of a `layout_strategy`
-  2. table <br>
+  2. table
       A table with possible keys `layout_strategy`, `layout_config` and `previewer`
 
   Default: { "horizontal", "vertical" }
@@ -241,7 +241,6 @@ append(
   [[
   The character(s) that will be shown in front of the current selection.
 
-
   Default: '> ']]
 )
 
@@ -289,7 +288,7 @@ append(
   "path_display",
   {},
   [[
-  Determines how file paths are displayed
+  Determines how file paths are displayed.
 
   path_display can be set to an array with a combination of:
   - "hidden"    hide file names
@@ -302,7 +301,7 @@ append(
   - "shorten"   only display the first character of each directory in
                 the path
   - "truncate"  truncates the start of the path when the whole path will
-                not fit. To increase the the gap between the path and the edge.
+                not fit. To increase the gap between the path and the edge,
                 set truncate to number `truncate = 3`
 
   You can also specify the number of characters of each directory name
@@ -418,7 +417,7 @@ append(
   [[
   Defines the default title of the prompt window. A false value
   can be used to hide the title altogether. Most of the times builtins
-  define a prompt_title which will be prefered over this default.
+  define a prompt_title which will be preferred over this default.
 
   Default: "Prompt"]]
 )
@@ -442,6 +441,8 @@ append(
 
   Will allow you to completely remove all of telescope's default maps
   and use your own.
+
+  Default: nil
   ]]
 )
 
@@ -469,11 +470,11 @@ append(
 
   Fields:
     - path:    The path to the telescope history as string.
-               default: stdpath("data")/telescope_history
+               Default: stdpath("data")/telescope_history
     - limit:   The amount of entries that will be written in the
                history.
                Warning: If limit is set to nil it will grow unbound.
-               default: 100
+               Default: 100
     - handler: A lua function that implements the history.
                This is meant as a developer setting for extensions to
                override the history handling, e.g.,
@@ -678,7 +679,7 @@ append(
   [[
   A function pointer that specifies the file_sorter. This sorter will
   be used for find_files, git_files and similar.
-  Hint: If you load a native sorter, you dont need to change this value,
+  Hint: If you load a native sorter, you don't need to change this value,
   the native sorter will override it anyway.
 
   Default: require("telescope.sorters").get_fzy_sorter]]
@@ -690,7 +691,7 @@ append(
   [[
   A function pointer to the generic sorter. The sorter that should be
   used for everything that is not a file.
-  Hint: If you load a native sorter, you dont need to change this value,
+  Hint: If you load a native sorter, you don't need to change this value,
   the native sorter will override it anyway.
 
   Default: require("telescope.sorters").get_fzy_sorter]]
@@ -703,7 +704,7 @@ append(
   [[
   This points to a wrapper sorter around the generic_sorter that is able
   to do prefiltering.
-  Its usually used for lsp_*_symbols and lsp_*_diagnostics
+  It's usually used for lsp_*_symbols and lsp_*_diagnostics
 
   Default: require("telescope.sorters").prefilter]]
 )

lua/telescope/init.lua

@@ -13,10 +13,10 @@ local telescope = {}
 ---
 --- Getting started with telescope:
 ---   1. Run `:checkhealth telescope` to make sure everything is installed.
----   2. Evaluate it working with
+---   2. Evaluate it is working with
 ---      `:Telescope find_files` or
 ---      `:lua require("telescope.builtin").find_files()`
----   3. Put a `require("telescope").setup() call somewhere in your neovim config.
+---   3. Put a `require("telescope").setup()` call somewhere in your neovim config.
 ---   4. Read |telescope.setup| to check what config keys are available and what you can put inside the setup call
 ---   5. Read |telescope.builtin| to check which builtin pickers are offered and what options these implement
 ---   6. Profit
@@ -31,14 +31,14 @@ local telescope = {}
 --- │            │   ┌───│Manager│────│ Sorter │┐    └───┬───*  │
 --- │            ▼   ▼   └───────*    └────────┘│        │      │
 --- │            1────────┐                 2───┴──┐     │      │
---- │      ┌─────│ Picker │                 │Finder│◄────┘      │
+--- │      ┌─────│ Picker │                 │Finder│◀────┘      │
 --- │      ▼     └───┬────┘                 └──────*            │
 --- │ ┌────────┐     │       3────────+         ▲               │
 --- │ │Selected│     └───────│ Prompt │─────────┘               │
 --- │ │ Entry  │             └───┬────┘                         │
 --- │ └────────*             ┌───┴────┐  ┌────────┐  ┌────────┐ │
 --- │     │  ▲    4─────────┐│ Prompt │  │(Attach)│  │Actions │ │
---- │     ▼  └──► │ Results ││ Buffer │◄─┤Mappings│◄─┤User Fn │ │
+--- │     ▼  └──▶ │ Results ││ Buffer │◀─┤Mappings│◀─┤User Fn │ │
 --- │5─────────┐  └─────────┘└────────┘  └────────┘  └────────┘ │
 --- ││Previewer│                                                │
 --- │└─────────┘                   telescope.nvim architecture  │

lua/telescope/make_entry.lua

@@ -11,24 +11,23 @@
 --- an entry. This function will return an entry table (or nil, meaning skip
 --- this entry) which contains the following important keys:
 --- - value any: value key can be anything but still required
---- - valid bool: is an optional key because it defaults to true but if the key
----   is set to false it will not be displayed by the picker (optional)
---- - ordinal string: is the text that is used for filtering (required)
+--- - valid bool (optional): is an optional key because it defaults to true but if the key
+---   is set to false it will not be displayed by the picker
+--- - ordinal string: is the text that is used for filtering
 --- - display string|function: is either a string of the text that is being
 ---   displayed or a function receiving the entry at a later stage, when the entry
 ---   is actually being displayed. A function can be useful here if a complex
----   calculation has to be done. `make_entry` can also return a second value
+---   calculation has to be done. `make_entry` can also return a second value -
 ---   a highlight array which will then apply to the line. Highlight entry in
 ---   this array has the following signature `{ { start_col, end_col }, hl_group }`
----   (required)
---- - filename string: will be interpreted by the default `<cr>` action as
----   open this file (optional)
---- - bufnr number: will be interpreted by the default `<cr>` action as open
----   this buffer (optional)
---- - lnum number: lnum value which will be interpreted by the default `<cr>`
----   action as a jump to this line (optional)
---- - col number: col value which will be interpreted by the default `<cr>`
----   action as a jump to this column (optional)
+--- - filename string (optional): will be interpreted by the default `<cr>` action as
+---   open this file
+--- - bufnr number (optional): will be interpreted by the default `<cr>` action as open
+---   this buffer
+--- - lnum number (optional): lnum value which will be interpreted by the default `<cr>`
+---   action as a jump to this line
+--- - col number (optional): col value which will be interpreted by the default `<cr>`
+---   action as a jump to this column
 ---
 --- For more information on easier displaying, see |telescope.pickers.entry_display|
 ---

lua/telescope/mappings.lua

@@ -2,12 +2,11 @@
 
 ---@brief [[
 --- |telescope.mappings| is used to configure the keybindings within
---- a telescope picker. These keybinds are only local to the picker window
+--- a telescope picker. These key binds are only local to the picker window
 --- and will be cleared once you exit the picker.
 ---
---- We provide multiple different ways of configuring, as described below,
---- to provide an easy to use experience for changing the default behavior
---- of telescope or extending for your own purposes.
+--- We provide multiple configuration options to make it easy for you to adjust
+--- telescope's default key bindings and create your own custom key binds.
 ---
 --- To see many of the builtin actions that you can use as values for this
 --- table, see |telescope.actions|
@@ -39,7 +38,6 @@
 ---     ...,
 ---   }
 --- </code>
----    Into your config.
 ---
 --- To override behavior of a key, simply set the value
 --- to be a function (either by requiring an action or by writing
@@ -53,7 +51,7 @@
 --- </code>
 ---
 ---  If the function you want is part of `telescope.actions`, then you can
----  simply give a string.
+---  simply supply the function name as a string.
 ---    For example, the previous option is equivalent to:
 --- <code>
 ---   {

lua/telescope/pickers/entry_display.lua

@@ -12,7 +12,7 @@
 --- for the best performance.
 ---
 --- The create function will use the column widths passed to it in
---- configaration.items. Each item in that table is the number of characters in
+--- configuration.items. Each item in that table is the number of characters in
 --- the column. It's also possible for the final column to not have a fixed
 --- width, this will be shown in the configuration as 'remaining = true'.
 ---

lua/telescope/pickers/layout_strategies.lua

@@ -38,7 +38,6 @@
 ---     - columns       : (number) Columns in the vim window
 ---     - lines         : (number) Lines in the vim window
 ---     - layout_config : (table) The configuration values specific to the picker.
----
 --- </pre>
 ---
 --- This means you can create your own layout strategy if you want! Just be aware
@@ -550,6 +549,7 @@ layout_strategies.center = make_documented_layout(
 --- │                                                  │
 --- └──────────────────────────────────────────────────┘
 --- </pre>
+---@eval { ["description"] = require("telescope.pickers.layout_strategies")._format("cursor") }
 layout_strategies.cursor = make_documented_layout(
   "cursor",
   vim.tbl_extend("error", {

lua/telescope/previewers/init.lua

@@ -221,8 +221,8 @@ previewers.qflist = term_previewer.qflist
 ---       vim.api.nvim_buf_call(bufnr, function()
 ---         -- for example `search` and `matchadd`
 ---       end)
----     to achieve that.
 --- </code>
+---     to achieve that.
 ---   - 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`

lua/telescope/themes.lua

@@ -19,9 +19,10 @@ local themes = {}
 ---
 --- Usage:
 --- <code>
----     `local builtin = require('telescope.builtin')`
----     `local themes = require('telescope.themes')`
----     `builtin.find_files(themes.get_dropdown())`
+---     local opts = {...} -- picker options
+---     local builtin = require('telescope.builtin')
+---     local themes = require('telescope.themes')
+---     builtin.find_files(themes.get_dropdown(opts))
 --- </code>
 function themes.get_dropdown(opts)
   opts = opts or {}
@@ -67,10 +68,10 @@ end
 ---
 --- Usage:
 --- <code>
----
----     `local builtin = require('telescope.builtin')`
----     `local themes = require('telescope.themes')`
----     `builtin.lsp_references(themes.get_cursor())`
+---     local opts = {...} -- picker options
+---     local builtin = require('telescope.builtin')
+---     local themes = require('telescope.themes')
+---     builtin.find_files(themes.get_cursor(opts))
 --- </code>
 function themes.get_cursor(opts)
   opts = opts or {}
@@ -99,9 +100,10 @@ end
 ---
 --- Usage:
 --- <code>
----     `local builtin = require('telescope.builtin')`
----     `local themes = require('telescope.themes')`
----     `builtin.find_files(themes.get_ivy())`
+---     local opts = {...} -- picker options
+---     local builtin = require('telescope.builtin')
+---     local themes = require('telescope.themes')
+---     builtin.find_files(themes.get_ivy(opts))
 --- </code>
 function themes.get_ivy(opts)
   opts = opts or {}

lua/telescope/utils.lua

@@ -211,7 +211,7 @@ end
 --- this function outside of telescope might yield to undefined behavior and will
 --- not be addressed by us
 ---@param opts table: The opts the users passed into the picker. Might contains a path_display key
----@param path string: The path that should be formated
+---@param path string: The path that should be formatted
 ---@return string: The transformed path ready to be displayed
 utils.transform_path = function(opts, path)
   if path == nil then