From edc6f55ba2565930310542b3023f00e88dd3e6a8 Mon Sep 17 00:00:00 2001
From: Simon Hauser <Simon-Hauser@outlook.de>
Date: Sun, 22 May 2022 11:32:55 +0200
Subject: [PATCH] docs: document limitations of file_ignore_patterns and
 transform_path (#1955)

---
 doc/telescope.txt        | 44 ++++++++++++++++++++++++++++++++++++++++
 lua/telescope/config.lua | 11 ++++++++++
 lua/telescope/utils.lua  | 17 ++++++++++++++++
 scripts/gendocs.lua      |  1 +
 4 files changed, 73 insertions(+)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index b79006b..0b769ee 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -655,6 +655,17 @@ telescope.setup({opts})                                    *telescope.setup()*
         Example: { "%.npz" } -- ignore all npz files
         See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more
         information about lua regex
+        Note: `file_ignore_patterns` will be used in all pickers that have a
+        file associated. This might lead to the problem that lsp_ pickers
+        aren't displaying results because they might be ignored by
+        `file_ignore_patterns`. For example, setting up node_modules as ignored
+        will never show node_modules in any results, even if you are
+        interested in lsp_ results.
+
+        If you only want `file_ignore_patterns` for `find_files` and
+        `grep_string`/`live_grep` it is suggested that you setup `gitignore`
+        and have fd and or ripgrep installed because both tools will not show
+        `gitignore`d files on default.
 
         Default: nil
 
@@ -1944,6 +1955,39 @@ resolver.resolve_anchor_pos()         *telescope.resolve.resolve_anchor_pos()*
 
 
 
+================================================================================
+                                                               *telescope.utils*
+
+Utilities for writing telescope pickers
+
+utils.transform_path({opts}, {path})        *telescope.utils.transform_path()*
+    Transform path is a util function that formats a path based on path_display
+    found in `opts` or the default value from config. It is meant to be used in
+    make_entry to have a uniform interface for builtins as well as extensions
+    utilizing the same user configuration Note: It is only supported inside
+    `make_entry`/`make_display` the use of this function outside of telescope
+    might yield to undefined behavior and will not be addressed by us
+
+
+    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
+
+    Return: ~
+        string: The transformed path ready to be displayed
+
+
+utils.notify({funname}, {opts})                     *telescope.utils.notify()*
+    Telescope Wrapper around vim.notify
+
+
+    Parameters: ~
+        {funname} (string)  name of the function that will be
+        {opts}    (table)   opts.level string, opts.msg string, opts.once bool
+
+
+
 ================================================================================
                                                              *telescope.actions*
 
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index f5cc3c6..88f8a59 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -783,6 +783,17 @@ append(
   Example: { "%.npz" } -- ignore all npz files
   See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more
   information about lua regex
+  Note: `file_ignore_patterns` will be used in all pickers that have a
+  file associated. This might lead to the problem that lsp_ pickers
+  aren't displaying results because they might be ignored by
+  `file_ignore_patterns`. For example, setting up node_modules as ignored
+  will never show node_modules in any results, even if you are
+  interested in lsp_ results.
+
+  If you only want `file_ignore_patterns` for `find_files` and
+  `grep_string`/`live_grep` it is suggested that you setup `gitignore`
+  and have fd and or ripgrep installed because both tools will not show
+  `gitignore`d files on default.
 
   Default: nil]]
 )
diff --git a/lua/telescope/utils.lua b/lua/telescope/utils.lua
index 2a8de58..7692409 100644
--- a/lua/telescope/utils.lua
+++ b/lua/telescope/utils.lua
@@ -1,3 +1,10 @@
+---@tag telescope.utils
+---@config { ["module"] = "telescope.utils" }
+
+---@brief [[
+--- Utilities for writing telescope pickers
+---@brief ]]
+
 local Path = require "plenary.path"
 local Job = require "plenary.job"
 
@@ -210,6 +217,16 @@ local calc_result_length = function(truncate_len)
   return type(truncate_len) == "number" and len - truncate_len or len
 end
 
+--- Transform path is a util function that formats a path based on path_display
+--- found in `opts` or the default value from config.
+--- It is meant to be used in make_entry to have a uniform interface for
+--- builtins as well as extensions utilizing the same user configuration
+--- Note: It is only supported inside `make_entry`/`make_display` the use of
+--- 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
+---@return string: The transformed path ready to be displayed
 utils.transform_path = function(opts, path)
   if path == nil then
     return
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 7016147..524cb04 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -17,6 +17,7 @@ docs.test = function()
     "./lua/telescope/themes.lua",
     "./lua/telescope/pickers/layout_strategies.lua",
     "./lua/telescope/config/resolve.lua",
+    "./lua/telescope/utils.lua",
     "./lua/telescope/actions/init.lua",
     "./lua/telescope/actions/state.lua",
     "./lua/telescope/actions/set.lua",