Skip to content

Commit

Permalink
docs: proof-read edits (#2311)
Browse files Browse the repository at this point in the history
  • Loading branch information
jamestrew authored Jan 22, 2023
1 parent ed366bb commit 053f230
Show file tree
Hide file tree
Showing 13 changed files with 151 additions and 136 deletions.
155 changes: 85 additions & 70 deletions doc/telescope.txt

Large diffs are not rendered by default.

14 changes: 7 additions & 7 deletions lua/telescope/actions/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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", ":")
Expand All @@ -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", "/")
Expand Down
8 changes: 4 additions & 4 deletions lua/telescope/actions/utils.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
14 changes: 7 additions & 7 deletions lua/telescope/builtin/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
23 changes: 12 additions & 11 deletions lua/telescope/config.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
Expand Down Expand Up @@ -241,7 +241,6 @@ append(
[[
The character(s) that will be shown in front of the current selection.
Default: '> ']]
)

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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"]]
)
Expand All @@ -442,6 +441,8 @@ append(
Will allow you to completely remove all of telescope's default maps
and use your own.
Default: nil
]]
)

Expand Down Expand Up @@ -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.,
Expand Down Expand Up @@ -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]]
Expand All @@ -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]]
Expand All @@ -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]]
)
Expand Down
8 changes: 4 additions & 4 deletions lua/telescope/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 │
Expand Down
25 changes: 12 additions & 13 deletions lua/telescope/make_entry.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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|
---
Expand Down
10 changes: 4 additions & 6 deletions lua/telescope/mappings.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand Down Expand Up @@ -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
Expand All @@ -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>
--- {
Expand Down
2 changes: 1 addition & 1 deletion lua/telescope/pickers/entry_display.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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'.
---
Expand Down
2 changes: 1 addition & 1 deletion lua/telescope/pickers/layout_strategies.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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", {
Expand Down
2 changes: 1 addition & 1 deletion lua/telescope/previewers/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Loading

0 comments on commit 053f230

Please sign in to comment.