From 3b8a1e17187cfeedb31decbd625da62398a8ff34 Mon Sep 17 00:00:00 2001 From: James Trew <66286082+jamestrew@users.noreply.github.com> Date: Sat, 21 Sep 2024 01:57:59 +0000 Subject: [PATCH] docs(help): clean up formatting (#403) --- doc/telescope-file-browser.txt | 83 ++++++++++--------- .../_extensions/file_browser/actions.lua | 57 ++++++------- .../_extensions/file_browser/finders.lua | 6 +- .../_extensions/file_browser/picker.lua | 12 +-- 4 files changed, 79 insertions(+), 79 deletions(-) diff --git a/doc/telescope-file-browser.txt b/doc/telescope-file-browser.txt index f52b1aa..7a46569 100644 --- a/doc/telescope-file-browser.txt +++ b/doc/telescope-file-browser.txt @@ -103,7 +103,6 @@ The `file_browser` picker comes pre-configured with several keymaps: • `/s`: Toggle all entries ignoring `./` and `../` • `/` : Goes to parent dir if prompt is empty, otherwise acts normally - The file browser picker can be configured with the following options: *telescope-file-browser.PickerOpts* @@ -232,11 +231,11 @@ fb_actions.create({prompt_bufnr}) • Finder: • file_browser: create a file in the currently opened directory • folder_browser: create a file in the currently selected directory - • Notes: - • You can create folders by ending the name in the path separator of - your OS, e.g. "/" on Unix systems - • You can implicitly create new folders by passing - $/CWD/new_folder/filename.lua + + Note: ~ + • You can create folders by ending the name in the path separator of your OS, + e.g. "/" on Unix systems + • You can implicitly create new folders by passing $/CWD/new_folder/filename.lua Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -245,11 +244,11 @@ fb_actions.create({prompt_bufnr}) fb_actions.create_from_prompt({prompt_bufnr}) Creates a new file or dir via prompt in the current directory of the |telescope-file-browser.picker.file_browser|. - • Notes: - • You can create folders by ending the name in the path separator of - your OS, e.g. "/" on Unix systems - • You can implicitly create new folders by passing - $/CWD/new_folder/filename.lua + + Note: ~ + • You can create folders by ending the name in the path separator of your OS, + e.g. "/" on Unix systems + • You can implicitly create new folders by passing $/CWD/new_folder/filename.lua Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -258,11 +257,11 @@ fb_actions.create_from_prompt({prompt_bufnr}) fb_actions.rename({prompt_bufnr}) Rename files or folders for |telescope-file-browser.picker.file_browser|. - Notes: - • Triggering renaming with multi selections opens `Batch Rename` window in - which the user can rename/move files multi-selected files at once - • In `Batch Rename`, the number of paths must persist: keeping a file name - means keeping the line unchanged + Note: ~ + • Triggering renaming with multi selections opens `Batch Rename` window + • in which the user can rename/move files multi-selected files at once + • In `Batch Rename`, the number of paths must persist: keeping a file name means + keeping the line unchanged Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -270,11 +269,11 @@ fb_actions.rename({prompt_bufnr}) fb_actions.move({prompt_bufnr}) *telescope-file-browser.actions.move()* Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|. - • Notes: + + Note: ~ • Performs a blocking synchronized file-system operation. - • Moving multi-selections is sensitive to order of selection, which - potentially unpacks files from parent(s) dirs if files are selected - first. + • Moving multi-selections is sensitive to order of selection, which potentially + unpacks files from parent(s) dirs if files are selected first. Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -296,7 +295,8 @@ fb_actions.remove({prompt_bufnr}) Remove file or folders recursively for |telescope-file-browser.picker.file_browser|. - Note: Performs a blocking synchronized file-system operation. + Note: ~ + • Performs a blocking synchronized file-system operation. Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -318,14 +318,15 @@ fb_actions.toggle_respect_gitignore({prompt_bufnr}) fb_actions.open() *telescope-file-browser.actions.open()* Opens the file or folder with the default application. - • Notes: + + Note: ~ • map fb_actions.open + fb_actions.close if you want to close the picker post-action - • OS: make sure your OS links against the desired applications: - • Linux: induces application via `xdg-open` - • macOS: relies on `open` to start the program - • Windows: defaults to default applications through `start` @pram - prompt_bufnr number: The prompt bufnr + • make sure your OS links against the desired applications: + • Linux: induces application via `xdg-open` + • macOS: relies on `open` to start the program + • Windows: defaults to default applications through `start` ram + prompt_bufnr number: The prompt bufnr *telescope-file-browser.actions.goto_parent_dir()* fb_actions.goto_parent_dir({prompt_bufnr}, {bypass}) @@ -371,8 +372,10 @@ fb_actions.toggle_browser({prompt_bufnr}) fb_actions.toggle_all({prompt_bufnr}) Toggles all selections akin to |telescope.actions.toggle_all| but ignores parent & current directory - • Note: if the parent or current directory were selected, they will be - ignored (manually unselect with ``) + + Note: ~ + • if the parent or current directory were selected, they will be ignored + (manually unselect with ``) Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -381,10 +384,11 @@ fb_actions.toggle_all({prompt_bufnr}) fb_actions.select_all({prompt_bufnr}) Multi select all entries akin to |telescope.actions.select_all| but ignores parent & current directory - • Note: + + Note: ~ • selected entries may include results not visible in the results popup. - • if the parent or current directly was previously selected, they will - be ignored in the selected state (manually unselect with ``) + • if the parent or current directly was previously selected, they will be + ignored in the selected state (manually unselect with ``) Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -392,7 +396,9 @@ fb_actions.select_all({prompt_bufnr}) *telescope-file-browser.actions.sort_by_size()* fb_actions.sort_by_size({prompt_bufnr}) Toggle sorting by size of the entry. - Note: initially sorts descendingly in size. + + Note: ~ + • initially sorts descendingly in size. Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -400,8 +406,9 @@ fb_actions.sort_by_size({prompt_bufnr}) *telescope-file-browser.actions.sort_by_date()* fb_actions.sort_by_date({prompt_bufnr}) Toggle sorting by last change to the entry. - Note: initially sorts desendingly from most to least recently changed - entry. + + Note: ~ + • initially sorts desendingly from most to least recently changed entry. Parameters: ~ • {prompt_bufnr} (`number`) The prompt bufnr @@ -447,7 +454,8 @@ The file browser finders power the picker with both a file and folder browser. *telescope-file-browser.finders.browse_files()* fb_finders.browse_files({opts}) Returns a finder that is populated with files and folders in `path`. - • Notes: + + Note: ~ • Uses `fd` if available for more async-ish browsing and speed-ups Parameters: ~ @@ -457,7 +465,8 @@ fb_finders.browse_files({opts}) *telescope-file-browser.finders.browse_folders()* fb_finders.browse_folders({opts}) Returns a finder that is populated with (sub-)folders of `cwd`. - • Notes: + + Note: ~ • Uses `fd` if available for more async-ish browsing and speed-ups Parameters: ~ diff --git a/lua/telescope/_extensions/file_browser/actions.lua b/lua/telescope/_extensions/file_browser/actions.lua index ee96d77..929dcec 100755 --- a/lua/telescope/_extensions/file_browser/actions.lua +++ b/lua/telescope/_extensions/file_browser/actions.lua @@ -137,11 +137,10 @@ end --- Creates a new file or dir in the current directory of the |telescope-file-browser.picker.file_browser|. --- - Finder: ---- - file_browser: create a file in the currently opened directory ---- - folder_browser: create a file in the currently selected directory ---- - Notes: ---- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems ---- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua +--- - file_browser: create a file in the currently opened directory +--- - folder_browser: create a file in the currently selected directory +---@note You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems +---@note You can implicitly create new folders by passing $/CWD/new_folder/filename.lua ---@param prompt_bufnr number: The prompt bufnr fb_actions.create = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -162,9 +161,8 @@ fb_actions.create = function(prompt_bufnr) end --- Creates a new file or dir via prompt in the current directory of the |telescope-file-browser.picker.file_browser|. ---- - Notes: ---- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems ---- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua +---@note You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems +---@note You can implicitly create new folders by passing $/CWD/new_folder/filename.lua ---@param prompt_bufnr number: The prompt bufnr fb_actions.create_from_prompt = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -278,10 +276,9 @@ end --- Rename files or folders for |telescope-file-browser.picker.file_browser|. --- ---- Notes: ---- - Triggering renaming with multi selections opens `Batch Rename` window ---- in which the user can rename/move files multi-selected files at once ---- - In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged +---@note Triggering renaming with multi selections opens `Batch Rename` window +---@note in which the user can rename/move files multi-selected files at once +---@note In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged ---@param prompt_bufnr number: The prompt bufnr fb_actions.rename = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -345,11 +342,9 @@ end --- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|. --- ---- - Notes: ---- - Performs a blocking synchronized file-system operation. ---- - Moving multi-selections is sensitive to order of selection, ---- which potentially unpacks files from parent(s) dirs ---- if files are selected first. +---@note Performs a blocking synchronized file-system operation. +---@note Moving multi-selections is sensitive to order of selection, which +--- potentially unpacks files from parent(s) dirs if files are selected first. ---@param prompt_bufnr number: The prompt bufnr fb_actions.move = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -403,8 +398,8 @@ end --- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|. --- --- - Finder: ---- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy) ---- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy) +--- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy) +--- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy) ---@param prompt_bufnr number: The prompt bufnr fb_actions.copy = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -500,7 +495,7 @@ end --- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|. --- ---- Note: Performs a blocking synchronized file-system operation. +---@note Performs a blocking synchronized file-system operation. ---@param prompt_bufnr number: The prompt bufnr fb_actions.remove = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -601,12 +596,11 @@ end --- Opens the file or folder with the default application. --- ---- - Notes: ---- - map fb_actions.open + fb_actions.close if you want to close the picker post-action ---- - OS: make sure your OS links against the desired applications: ---- - Linux: induces application via `xdg-open` ---- - macOS: relies on `open` to start the program ---- - Windows: defaults to default applications through `start` +---@note map fb_actions.open + fb_actions.close if you want to close the picker post-action +---@note make sure your OS links against the desired applications: +--- - Linux: induces application via `xdg-open` +--- - macOS: relies on `open` to start the program +--- - Windows: defaults to default applications through `start` ---@pram prompt_bufnr number: The prompt bufnr fb_actions.open = function(prompt_bufnr) local quiet = action_state.get_current_picker(prompt_bufnr).finder.quiet @@ -720,7 +714,7 @@ fb_actions.toggle_browser = function(prompt_bufnr, opts) end --- Toggles all selections akin to |telescope.actions.toggle_all| but ignores parent & current directory ---- - Note: if the parent or current directory were selected, they will be ignored (manually unselect with ``) +---@note if the parent or current directory were selected, they will be ignored (manually unselect with ``) ---@param prompt_bufnr number: The prompt bufnr fb_actions.toggle_all = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -742,9 +736,8 @@ fb_actions.toggle_all = function(prompt_bufnr) end --- Multi select all entries akin to |telescope.actions.select_all| but ignores parent & current directory ---- - Note: ---- - selected entries may include results not visible in the results popup. ---- - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with ``) +---@note selected entries may include results not visible in the results popup. +---@note if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with ``) ---@param prompt_bufnr number: The prompt bufnr fb_actions.select_all = function(prompt_bufnr) local current_picker = action_state.get_current_picker(prompt_bufnr) @@ -789,7 +782,7 @@ local sort_by = function(prompt_bufnr, sorter_fn) end --- Toggle sorting by size of the entry.
---- Note: initially sorts descendingly in size. +---@note initially sorts descendingly in size. ---@param prompt_bufnr number: The prompt bufnr fb_actions.sort_by_size = function(prompt_bufnr) local finder = action_state.get_current_picker(prompt_bufnr).finder @@ -813,7 +806,7 @@ fb_actions.sort_by_size = function(prompt_bufnr) end --- Toggle sorting by last change to the entry.
---- Note: initially sorts desendingly from most to least recently changed entry. +---@note initially sorts desendingly from most to least recently changed entry. ---@param prompt_bufnr number: The prompt bufnr fb_actions.sort_by_date = function(prompt_bufnr) local finder = action_state.get_current_picker(prompt_bufnr).finder diff --git a/lua/telescope/_extensions/file_browser/finders.lua b/lua/telescope/_extensions/file_browser/finders.lua index a5bae2a..fd3b67d 100644 --- a/lua/telescope/_extensions/file_browser/finders.lua +++ b/lua/telescope/_extensions/file_browser/finders.lua @@ -82,8 +82,7 @@ local function git_args() end --- Returns a finder that is populated with files and folders in `path`. ---- - Notes: ---- - Uses `fd` if available for more async-ish browsing and speed-ups +---@note Uses `fd` if available for more async-ish browsing and speed-ups ---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder fb_finders.browse_files = function(opts) opts = opts or {} @@ -136,8 +135,7 @@ fb_finders.browse_files = function(opts) end --- Returns a finder that is populated with (sub-)folders of `cwd`. ---- - Notes: ---- - Uses `fd` if available for more async-ish browsing and speed-ups +---@note Uses `fd` if available for more async-ish browsing and speed-ups ---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder fb_finders.browse_folders = function(opts) opts = opts or {} diff --git a/lua/telescope/_extensions/file_browser/picker.lua b/lua/telescope/_extensions/file_browser/picker.lua index 2e4eb90..42ae7ad 100644 --- a/lua/telescope/_extensions/file_browser/picker.lua +++ b/lua/telescope/_extensions/file_browser/picker.lua @@ -35,7 +35,7 @@ --- - `/` : Goes to parent dir if prompt is empty, otherwise acts normally --- --- ----
The file browser picker can be configured with the following options: +--- The file browser picker can be configured with the following options: local pickers = require "telescope.pickers" local conf = require("telescope.config").values @@ -103,11 +103,11 @@ local fb_picker = {} --- --- Notes: --- - display_stat: ---- - A table that can currently hold `date` and/or `size` as keys -- order matters! ---- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly ---- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }` ---- - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }` ---- - See make_entry.lua for an example on how to further customize +--- - A table that can currently hold `date` and/or `size` as keys -- order matters! +--- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly +--- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }` +--- - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }` +--- - See make_entry.lua for an example on how to further customize ---@class telescope-file-browser.PickerOpts : telescope.picker.opts ---@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`) ---@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)