docs(help): clean up formatting

doc/telescope-file-browser.txt

@@ -44,7 +44,7 @@ https://github.com/nvim-telescope/telescope-file-browser.nvim
   :h |telescope-file-browser.finders|
 
 *telescope-file-browser.SetupOpts*
-Extends |telescope-file-browser.PickerOpts|
+    Extends |telescope-file-browser.PickerOpts|
 
     Fields: ~
       • {hijack_netrw}  (`boolean?`, default: `false`) use telescope file
@@ -63,6 +63,7 @@ Extends |telescope-file-browser.PickerOpts|
                           general telescope mappings/actions and
                           implementation details By default,
 
+
 ==============================================================================
 PICKER                                         *telescope-file-browser.picker*
 
@@ -73,7 +74,7 @@ You can use the file browser as follows >lua
       "<cmd>Telescope file_browser<CR>",
       { noremap = true }
     )
-    
+
     -- or alternatively using lua functions
     local picker = require "telescope._extensions.file_browser"
     vim.api.keymap.set("n", "<space>fb", function()
@@ -85,7 +86,7 @@ The `file_browser` picker comes pre-configured with several keymaps:
   in the prompt
 • `<s-cr>` : Create path in prompt
 • `/`, `\` : (OS Path separator) When typing filepath, the path separator will
-  open a directory like `<cr>` .
+  open a directory like `<cr>`.
 • `<A-c>/c`: Create file/folder at current `path` (trailing path separator
   creates folder)
 • `<A-r>/r`: Rename multi-selected files/folders
@@ -102,11 +103,10 @@ 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*
-Extends |telescope.picker.opts|
+    Extends |telescope.picker.opts|
     Options for the file browser picker.
 
     Inherits options for the base telescope picker.
@@ -197,6 +197,7 @@ fb_picker.file_browser({opts})
       • {opts}  (`telescope-file-browser.PickerOpts?`) options to pass to the
                 picker. See |telescope-file-browser.PickerOpts|
 
+
 ==============================================================================
 ACTIONS                                       *telescope-file-browser.actions*
 
@@ -230,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
@@ -243,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
@@ -256,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
@@ -294,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
@@ -316,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})
@@ -369,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
@@ -379,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
@@ -428,13 +437,14 @@ fb_actions.open_dir({prompt_bufnr}, {_}, {dir})
       • {prompt_bufnr}  (`integer`)
       • {dir}           (`string?`) priority dir path
 
+
 ==============================================================================
 FINDERS                                       *telescope-file-browser.finders*
 
 The file browser finders power the picker with both a file and folder browser.
 
 *telescope-file-browser.FinderOpts*
-Extends |telescope-file-browser.PickerOpts|
+    Extends |telescope-file-browser.PickerOpts|
 
     Fields: ~
       • {entry_maker}  (`fun(opts: table): function`) entry maker for the
@@ -443,19 +453,21 @@ Extends |telescope-file-browser.PickerOpts|
 
                                *telescope-file-browser.finders.browse_files()*
 fb_finders.browse_files({opts})
-    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
+    Returns a finder that is populated with files and folders in `path`.
+
+    Note: ~
+      • Uses `fd` if available for more async-ish browsing and speed-ups
 
     Parameters: ~
       • {opts}  (`telescope-file-browser.FinderOpts?`) options to pass to the
                 finder. See |telescope-file-browser.FinderOpts|
 
                              *telescope-file-browser.finders.browse_folders()*
 fb_finders.browse_folders({opts})
-    Returns a finder that is populated with (sub-)folders of `cwd` .
-    • Notes:
-    • Uses `fd` if available for more async-ish browsing and speed-ups
+    Returns a finder that is populated with (sub-)folders of `cwd`.
+
+    Note: ~
+      • Uses `fd` if available for more async-ish browsing and speed-ups
 
     Parameters: ~
       • {opts}  (`telescope-file-browser.FinderOpts?`) options to pass to the
@@ -472,4 +484,5 @@ fb_finders.finder({opts})            *telescope-file-browser.finders.finder()*
     Return: ~
         (`table`) telescope finder
 
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

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