docs(help): clean up formatting (#403)

doc/telescope-file-browser.txt

@@ -103,7 +103,6 @@ The `file_browser` picker comes pre-configured with several keymaps:
 • `<C-s>/s`: Toggle all entries ignoring `./` and `../`
 • `<bs>/` : 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,23 +257,23 @@ 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
 
 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 `<TAB>`)
+
+    Note: ~
+      • if the parent or current directory were selected, they will be ignored
+        (manually unselect with `<TAB>`)
 
     Parameters: ~
       • {prompt_bufnr}  (`number`) The prompt bufnr
@@ -381,27 +384,31 @@ 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 `<TAB>`)
+      • if the parent or current directly was previously selected, they will be
+        ignored in the selected state (manually unselect with `<TAB>`)
 
     Parameters: ~
       • {prompt_bufnr}  (`number`) The 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
 
                                *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: ~

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 `<TAB>`)
+---@note if the parent or current directory were selected, they will be ignored (manually unselect with `<TAB>`)
 ---@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 `<TAB>`)
+---@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 `<TAB>`)
 ---@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.<br>
---- 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.<br>
---- 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

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 {}

lua/telescope/_extensions/file_browser/picker.lua

@@ -35,7 +35,7 @@
 --- - `<bs>/`  : Goes to parent dir if prompt is empty, otherwise acts normally
 ---
 ---
---- <br>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()`)