From 053f2303c4fac5c45a56b9de0a7481b7db94d6ba Mon Sep 17 00:00:00 2001
From: James Trew <66286082+jamestrew@users.noreply.github.com>
Date: Sun, 22 Jan 2023 03:57:53 -0500
Subject: [PATCH] docs: proof-read edits (#2311)

---
 doc/telescope.txt                           | 155 +++++++++++---------
 lua/telescope/actions/init.lua              |  14 +-
 lua/telescope/actions/utils.lua             |   8 +-
 lua/telescope/builtin/init.lua              |  14 +-
 lua/telescope/config.lua                    |  23 +--
 lua/telescope/init.lua                      |   8 +-
 lua/telescope/make_entry.lua                |  25 ++--
 lua/telescope/mappings.lua                  |  10 +-
 lua/telescope/pickers/entry_display.lua     |   2 +-
 lua/telescope/pickers/layout_strategies.lua |   2 +-
 lua/telescope/previewers/init.lua           |   2 +-
 lua/telescope/themes.lua                    |  22 +--
 lua/telescope/utils.lua                     |   2 +-
 13 files changed, 151 insertions(+), 136 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index ddfd9df..6c9a9d2 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -6,9 +6,9 @@ filter, find and pick things in Lua.
 
 Getting started with telescope:
   1. Run `:checkhealth telescope` to make sure everything is installed.
-  2. Evaluate it working with `:Telescope find_files` or `:lua
+  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
@@ -24,14 +24,14 @@ The below flow chart illustrates a simplified telescope architecture:
 │            │   ┌───│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  │
@@ -196,9 +196,9 @@ telescope.setup({opts})                                    *telescope.setup()*
         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" }
@@ -227,7 +227,6 @@ telescope.setup({opts})                                    *telescope.setup()*
     selection_caret: ~
         The character(s) that will be shown in front of the current selection.
 
-
         Default: '> '
 
                                           *telescope.defaults.entry_prefix*
@@ -260,7 +259,7 @@ telescope.setup({opts})                                    *telescope.setup()*
 
                                           *telescope.defaults.path_display*
     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
@@ -273,7 +272,7 @@ telescope.setup({opts})                                    *telescope.setup()*
         - "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
@@ -352,7 +351,7 @@ telescope.setup({opts})                                    *telescope.setup()*
     prompt_title: ~
         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"
 
@@ -371,6 +370,8 @@ telescope.setup({opts})                                    *telescope.setup()*
         Will allow you to completely remove all of telescope's default maps
         and use your own.
 
+        Default: nil
+
 
                                                *telescope.defaults.history*
     history: ~
@@ -388,11 +389,11 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         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.,
@@ -566,7 +567,7 @@ telescope.setup({opts})                                    *telescope.setup()*
     file_sorter: ~
         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
@@ -575,7 +576,7 @@ telescope.setup({opts})                                    *telescope.setup()*
     generic_sorter: ~
         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
@@ -584,7 +585,7 @@ telescope.setup({opts})                                    *telescope.setup()*
     prefilter_sorter: ~
         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
 
@@ -896,7 +897,7 @@ builtin.current_buffer_fuzzy_find({opts}) *telescope.builtin.current_buffer_fuzz
         {opts} (table)  options to pass to the picker
 
     Options: ~
-        {skip_empty_lines} (boolean)  if true we dont display empty lines
+        {skip_empty_lines} (boolean)  if true we don't display empty lines
                                       (default: false)
 
 
@@ -965,7 +966,7 @@ builtin.git_files({opts})                      *telescope.builtin.git_files()*
         {recurse_submodules} (boolean)  if true, adds the
                                         `--recurse-submodules` flag to command
                                         (default: false)
-        {git_command}        (table)    command that will be exectued.
+        {git_command}        (table)    command that will be executed.
                                         {"git","ls-files","--exclude-standard","--cached"}
 
 
@@ -985,13 +986,13 @@ builtin.git_commits({opts})                  *telescope.builtin.git_commits()*
         {cwd}          (string)   specify the path of the repo
         {use_git_root} (boolean)  if we should use git root as cwd or the cwd
                                   (important for submodule) (default: true)
-        {git_command}  (table)    command that will be exectued.
+        {git_command}  (table)    command that will be executed.
                                   {"git","log","--pretty=oneline","--abbrev-commit","--","."}
 
 
 builtin.git_bcommits({opts})                *telescope.builtin.git_bcommits()*
     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
@@ -1007,7 +1008,7 @@ builtin.git_bcommits({opts})                *telescope.builtin.git_bcommits()*
                                   (important for submodule) (default: true)
         {current_file} (string)   specify the current file that should be used
                                   for bcommits (default: current buffer)
-        {git_command}  (table)    command that will be exectued.
+        {git_command}  (table)    command that will be executed.
                                   {"git","log","--pretty=oneline","--abbrev-commit"}
 
 
@@ -1129,9 +1130,9 @@ builtin.planets({opts})                          *telescope.builtin.planets()*
         {opts} (table)  options to pass to the picker
 
     Options: ~
-        {show_pluto} (boolean)  we love pluto (default: false, because its a
+        {show_pluto} (boolean)  we love Pluto (default: false, because its a
                                 hidden feature)
-        {show_moon}  (boolean)  we love the moon (default: false, because its
+        {show_moon}  (boolean)  we love the Moon (default: false, because its
                                 a hidden feature)
 
 
@@ -1654,9 +1655,10 @@ themes.get_dropdown()                        *telescope.themes.get_dropdown()*
 
     Usage:
     >
-        `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))
 <
 
 
@@ -1666,10 +1668,10 @@ themes.get_cursor()                            *telescope.themes.get_cursor()*
 
     Usage:
     >
-
-        `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))
 <
 
 
@@ -1679,9 +1681,10 @@ themes.get_ivy()                                  *telescope.themes.get_ivy()*
 
     Usage:
     >
-        `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))
 <
 
 
@@ -1691,12 +1694,11 @@ themes.get_ivy()                                  *telescope.themes.get_ivy()*
 MAPPINGS                                                    *telescope.mappings*
 
 |telescope.mappings| is used to configure the keybindings within a telescope
-picker. These keybinds are only local to the picker window and will be cleared
+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|
@@ -1729,7 +1731,6 @@ For example:
     ...,
   }
 <
-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 your own function)
@@ -1742,7 +1743,8 @@ requiring an action or by writing your own function)
 <
 
 If the function you want is part of `telescope.actions`, then you can simply
-give a string. For example, the previous option is equivalent to:
+supply the function name as a string. For example, the previous option is
+equivalent to:
 >
   {
     ...,
@@ -1854,7 +1856,6 @@ All layout strategies are functions with the following signature:
     - lines         : (number) Lines in the vim window
     - layout_config : (table) The configuration values specific to the picker.
 
-
 This means you can create your own layout strategy if you want! Just be aware
 for now that we may change some APIs or interfaces, so they may break if you
 create your own.
@@ -1979,6 +1980,20 @@ layout_strategies.cursor()                         *telescope.layout.cursor()*
     │                                                  │
     └──────────────────────────────────────────────────┘
 
+    `picker.layout_config` shared options:
+      - height:
+        - How tall to make Telescope's entire layout
+        - See |resolver.resolve_height()|
+      - scroll_speed: The number of lines to scroll through the previewer
+      - width:
+        - How wide to make Telescope's entire layout
+        - See |resolver.resolve_width()|
+
+    `picker.layout_config` unique options:
+      - preview_cutoff: When columns are less than this value, the preview will be disabled
+      - preview_width:
+        - Change the width of Telescope's preview window
+        - See |resolver.resolve_width()|
 
 
 layout_strategies.vertical()                     *telescope.layout.vertical()*
@@ -2141,24 +2156,23 @@ Every entry maker returns a function that accepts the data to be used for 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 a
+  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)
+  array has the following signature `{ { start_col, end_col }, hl_group }`
+- 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|
@@ -2180,7 +2194,7 @@ every single entry. So it is suggested to do this outside of `make_display` 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 the
+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'.
 
@@ -2243,7 +2257,7 @@ utils.transform_path({opts}, {path})        *telescope.utils.transform_path()*
     Parameters: ~
         {opts} (table)   The opts the users passed into the picker. Might
                          contains a path_display key
-        {path} (string)  The path that should be formated
+        {path} (string)  The path that should be formatted
 
     Return: ~
         string: The transformed path ready to be displayed
@@ -2262,9 +2276,9 @@ utils.notify({funname}, {opts})                     *telescope.utils.notify()*
 ================================================================================
 ACTIONS                                                      *telescope.actions*
 
-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 first
+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
@@ -2305,8 +2319,8 @@ do the following:
   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)`,
+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` file.
 
@@ -2392,8 +2406,8 @@ actions.toggle_selection({prompt_bufnr}) *telescope.actions.toggle_selection()*
 
 actions.select_all({prompt_bufnr})            *telescope.actions.select_all()*
     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.
 
 
     Parameters: ~
@@ -2410,8 +2424,8 @@ actions.drop_all({prompt_bufnr})                *telescope.actions.drop_all()*
 
 actions.toggle_all({prompt_bufnr})            *telescope.actions.toggle_all()*
     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.
 
 
     Parameters: ~
@@ -2580,7 +2594,7 @@ actions._close({prompt_bufnr})                    *telescope.actions._close()*
 
 
 actions.edit_command_line({prompt_bufnr}) *telescope.actions.edit_command_line()*
-    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.
 
 
     Parameters: ~
@@ -2596,7 +2610,7 @@ actions.set_command_line({prompt_bufnr}) *telescope.actions.set_command_line()*
 
 
 actions.edit_search_line({prompt_bufnr}) *telescope.actions.edit_search_line()*
-    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.
 
 
     Parameters: ~
@@ -3120,7 +3134,7 @@ utils.map_entries({prompt_bufnr}, {f}) *telescope.actions.utils.map_entries()*
     Apply `f` to the entries of the current picker.
     - Notes:
       - Mapped entries include all currently filtered results, not just the
-        visible onces.
+        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
@@ -3133,7 +3147,7 @@ utils.map_entries({prompt_bufnr}, {f}) *telescope.actions.utils.map_entries()*
         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
@@ -3152,7 +3166,8 @@ utils.map_selections({prompt_bufnr}, {f}) *telescope.actions.utils.map_selection
     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
@@ -3165,7 +3180,7 @@ utils.map_selections({prompt_bufnr}, {f}) *telescope.actions.utils.map_selection
         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
@@ -3483,8 +3498,8 @@ previewers.new_buffer_previewer() *telescope.previewers.new_buffer_previewer()*
           vim.api.nvim_buf_call(bufnr, function()
             -- for example `search` and `matchadd`
           end)
-        to achieve that.
 <
+    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` because it
diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index 3a6ccc7..49619da 100644
--- a/lua/telescope/actions/init.lua
+++ b/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", "/")
diff --git a/lua/telescope/actions/utils.lua b/lua/telescope/actions/utils.lua
index 8018d64..5816baa 100644
--- a/lua/telescope/actions/utils.lua
+++ b/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
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 0f4c998..3036820 100644
--- a/lua/telescope/builtin/init.lua
+++ b/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
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index 7b45bda..9706933 100644
--- a/lua/telescope/config.lua
+++ b/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]]
 )
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index c267f06..acb56e7 100644
--- a/lua/telescope/init.lua
+++ b/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  │
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index ce34ba0..450ebee 100644
--- a/lua/telescope/make_entry.lua
+++ b/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|
 ---
diff --git a/lua/telescope/mappings.lua b/lua/telescope/mappings.lua
index 45fad81..60ccc27 100644
--- a/lua/telescope/mappings.lua
+++ b/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>
 ---   {
diff --git a/lua/telescope/pickers/entry_display.lua b/lua/telescope/pickers/entry_display.lua
index 864e2b3..d201bdd 100644
--- a/lua/telescope/pickers/entry_display.lua
+++ b/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'.
 ---
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index 7af7761..6bf49ee 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/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", {
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index 4b20f06..55e587e 100644
--- a/lua/telescope/previewers/init.lua
+++ b/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`
diff --git a/lua/telescope/themes.lua b/lua/telescope/themes.lua
index 0fe5d99..69d12e8 100644
--- a/lua/telescope/themes.lua
+++ b/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 {}
diff --git a/lua/telescope/utils.lua b/lua/telescope/utils.lua
index f2ab21e..0e2eb06 100644
--- a/lua/telescope/utils.lua
+++ b/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