docs: mappings documentation overhaul (#2065)

Co-authored-by: TJ DeVries <devries.timothyj@gmail.com>

5 files changed, 317 insertions, 205 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 2564854..437d537 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -119,20 +119,6 @@ telescope.setup({opts})                                    *telescope.setup()*
         - "descending" (default)
         - "ascending"
 
-                                              *telescope.defaults.tiebreak*
-    tiebreak: ~
-        A function that determines how to break a tie when two entries have
-        the same score.
-        Having a function that always returns false would keep the entries in
-        the order they are found, so existing_entry before current_entry.
-        Vice versa always returning true would place the current_entry
-        before the existing_entry.
-
-        Signature: function(current_entry, existing_entry, prompt) -> boolean
-
-        Default: function that breaks the tie based on the length of the
-                 entry's ordinal
-
                                     *telescope.defaults.selection_strategy*
     selection_strategy: ~
         Determines how the cursor acts after each sort iteration.
@@ -370,6 +356,22 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: "Prompt"
 
+                                              *telescope.defaults.mappings*
+    mappings: ~
+        Your mappings to override telescope's default mappings.
+
+        See: ~
+            |telescope.mappings|
+
+
+                                      *telescope.defaults.default_mappings*
+    default_mappings: ~
+        Not recommended to use except for advanced users.
+
+        Will allow you to completely remove all of telescope's default maps
+        and use your own.
+
+
                                                *telescope.defaults.history*
     history: ~
         This field handles the configuration for prompt history.
@@ -559,79 +561,6 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: true
 
-                                              *telescope.defaults.mappings*
-    mappings: ~
-        Your mappings to override telescope's default mappings.
-
-        Format is:
-        {
-          mode = { ..keys }
-        }
-
-        where {mode} is the one character letter for a mode
-        ('i' for insert, 'n' for normal).
-
-        For example:
-
-        mappings = {
-          i = {
-            ["<esc>"] = require('telescope.actions').close,
-          },
-        }
-
-
-        To disable a keymap, put [map] = false
-          So, to not map "<C-n>", just put
-
-            ...,
-            ["<C-n>"] = false,
-            ...,
-
-          Into your config.
-
-
-        otherwise, just set the mapping to the function that you want it to
-        be.
-
-            ...,
-            ["<C-i>"] = require('telescope.actions').select_default,
-            ...,
-
-        If the function you want is part of `telescope.actions`, then you can
-        simply give a string.
-          For example, the previous option is equivalent to:
-
-            ...,
-            ["<C-i>"] = "select_default",
-            ...,
-
-        You can also add other mappings using tables with `type = "command"`.
-          For example:
-
-            ...,
-            ["jj"] = { "<esc>", type = "command" },
-            ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
-            ...,
-
-        You can also add additional options for mappings of any type
-        ("action" and "command"). For example:
-
-            ...,
-            ["<C-j>"] = {
-              action = actions.move_selection_next,
-              opts = { nowait = true, silent = true }
-            },
-            ...,
-
-
-                                      *telescope.defaults.default_mappings*
-    default_mappings: ~
-        Not recommended to use except for advanced users.
-
-        Will allow you to completely remove all of telescope's default maps
-        and use your own.
-
-
                                            *telescope.defaults.file_sorter*
     file_sorter: ~
         A function pointer that specifies the file_sorter. This sorter will
@@ -658,6 +587,20 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: require("telescope.sorters").prefilter
 
+                                              *telescope.defaults.tiebreak*
+    tiebreak: ~
+        A function that determines how to break a tie when two entries have
+        the same score.
+        Having a function that always returns false would keep the entries in
+        the order they are found, so existing_entry before current_entry.
+        Vice versa always returning true would place the current_entry
+        before the existing_entry.
+
+        Signature: function(current_entry, existing_entry, prompt) -> boolean
+
+        Default: function that breaks the tie based on the length of the
+                 entry's ordinal
+
                                   *telescope.defaults.file_ignore_patterns*
     file_ignore_patterns: ~
         A table of lua regex that define the files that should be ignored.
@@ -1717,6 +1660,128 @@ themes.get_ivy()                                  *telescope.themes.get_ivy()*
 
 
 ================================================================================
+MAPPINGS                                                    *telescope.mappings*
+
+|telescope.mappings| is used to configure the keybindings within a telescope
+picker. These keybinds 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.
+
+To see many of the builtin actions that you can use as values for this table,
+see |telescope.actions|
+
+Format is:
+>
+  {
+    mode = { ..keys }
+  }
+<
+
+where {mode} is the one character letter for a mode ('i' for insert, 'n' for
+normal).
+
+For example:
+>
+  mappings = {
+    i = {
+      ["<esc>"] = require('telescope.actions').close,
+    },
+  }
+<
+
+To disable a keymap, put `[map] = false`
+For example:
+>
+  {
+    ...,
+    ["<C-n>"] = false,
+    ...,
+  }
+<
+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 your own function)
+>
+  {
+    ...,
+    ["<C-i>"] = require('telescope.actions').select_default,
+    ...,
+  }
+<
+
+If the function you want is part of `telescope.actions`, then you can simply
+give a string. For example, the previous option is equivalent to:
+>
+  {
+    ...,
+    ["<C-i>"] = "select_default",
+    ...,
+  }
+<
+
+You can also add other mappings using tables with `type = "command"`. For
+example:
+>
+  {
+    ...,
+    ["jj"] = { "<esc>", type = "command" },
+    ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
+    ...,
+  }
+<
+
+You can also add additional options for mappings of any type ("action" and
+"command"). For example:
+>
+  {
+    ...,
+    ["<C-j>"] = {
+      action = actions.move_selection_next,
+      opts = { nowait = true, silent = true }
+    },
+    ...,
+  }
+<
+
+There are three main places you can configure |telescope.mappings|. These are
+ordered from the lowest priority to the highest priority.
+
+1. |telescope.defaults.mappings|
+2. In the |telescope.setup()| table, inside a picker with a given name, use the
+   `mappings` key
+>
+  require("telescope").setup {
+    pickers = {
+      find_files = {
+        mappings = {
+          n = {
+            ["kj"] = "close",
+          },
+        },
+      },
+    },
+  }
+<
+3. `attach_mappings` function for a particular picker.
+>
+  require("telescope.builtin").find_files {
+    attach_mappings = function(_, map)
+      map("i", "asdf", function(_prompt_bufnr)
+        print "You typed asdf"
+      end)
+      -- needs to return true if you want to map default_mappings and
+      -- false if not
+      return true
+    end,
+  }
+<
+
+
+================================================================================
 LAYOUT                                                        *telescope.layout*
 
 The layout of telescope pickers can be adjusted using the
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index 8198ee2..db77491 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -153,25 +153,6 @@ append(
 )
 
 append(
-  "tiebreak",
-  function(current_entry, existing_entry, _)
-    return #current_entry.ordinal < #existing_entry.ordinal
-  end,
-  [[
-  A function that determines how to break a tie when two entries have
-  the same score.
-  Having a function that always returns false would keep the entries in
-  the order they are found, so existing_entry before current_entry.
-  Vice versa always returning true would place the current_entry
-  before the existing_entry.
-
-  Signature: function(current_entry, existing_entry, prompt) -> boolean
-
-  Default: function that breaks the tie based on the length of the
-           entry's ordinal]]
-)
-
-append(
   "selection_strategy",
   "reset",
   [[
@@ -443,6 +424,28 @@ append(
 )
 
 append(
+  "mappings",
+  {},
+  [[
+  Your mappings to override telescope's default mappings.
+
+  See: ~
+      |telescope.mappings|
+  ]]
+)
+
+append(
+  "default_mappings",
+  nil,
+  [[
+  Not recommended to use except for advanced users.
+
+  Will allow you to completely remove all of telescope's default maps
+  and use your own.
+  ]]
+)
+
+append(
   "history",
   {
     path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
@@ -669,85 +672,6 @@ append(
 )
 
 append(
-  "mappings",
-  {},
-  [[
-  Your mappings to override telescope's default mappings.
-
-  Format is:
-  {
-    mode = { ..keys }
-  }
-
-  where {mode} is the one character letter for a mode
-  ('i' for insert, 'n' for normal).
-
-  For example:
-
-  mappings = {
-    i = {
-      ["<esc>"] = require('telescope.actions').close,
-    },
-  }
-
-
-  To disable a keymap, put [map] = false
-    So, to not map "<C-n>", just put
-
-      ...,
-      ["<C-n>"] = false,
-      ...,
-
-    Into your config.
-
-
-  otherwise, just set the mapping to the function that you want it to
-  be.
-
-      ...,
-      ["<C-i>"] = require('telescope.actions').select_default,
-      ...,
-
-  If the function you want is part of `telescope.actions`, then you can
-  simply give a string.
-    For example, the previous option is equivalent to:
-
-      ...,
-      ["<C-i>"] = "select_default",
-      ...,
-
-  You can also add other mappings using tables with `type = "command"`.
-    For example:
-
-      ...,
-      ["jj"] = { "<esc>", type = "command" },
-      ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
-      ...,
-
-  You can also add additional options for mappings of any type
-  ("action" and "command"). For example:
-
-      ...,
-      ["<C-j>"] = {
-        action = actions.move_selection_next,
-        opts = { nowait = true, silent = true }
-      },
-      ...,
-  ]]
-)
-
-append(
-  "default_mappings",
-  nil,
-  [[
-  Not recommended to use except for advanced users.
-
-  Will allow you to completely remove all of telescope's default maps
-  and use your own.
-  ]]
-)
-
-append(
   "file_sorter",
   sorters.get_fzy_sorter,
   [[
@@ -784,6 +708,25 @@ append(
 )
 
 append(
+  "tiebreak",
+  function(current_entry, existing_entry, _)
+    return #current_entry.ordinal < #existing_entry.ordinal
+  end,
+  [[
+  A function that determines how to break a tie when two entries have
+  the same score.
+  Having a function that always returns false would keep the entries in
+  the order they are found, so existing_entry before current_entry.
+  Vice versa always returning true would place the current_entry
+  before the existing_entry.
+
+  Signature: function(current_entry, existing_entry, prompt) -> boolean
+
+  Default: function that breaks the tie based on the length of the
+           entry's ordinal]]
+)
+
+append(
   "file_ignore_patterns",
   nil,
   [[
diff --git a/lua/telescope/mappings.lua b/lua/telescope/mappings.lua
index b7baf41..04fbda2 100644
--- a/lua/telescope/mappings.lua
+++ b/lua/telescope/mappings.lua
@@ -1,4 +1,125 @@
--- TODO: Customize keymap
+---@tag telescope.mappings
+
+---@brief [[
+--- |telescope.mappings| is used to configure the keybindings within
+--- a telescope picker. These keybinds 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.
+---
+--- To see many of the builtin actions that you can use as values for this
+--- table, see |telescope.actions|
+---
+--- Format is:
+--- <code>
+---   {
+---     mode = { ..keys }
+---   }
+--- </code>
+---
+---  where {mode} is the one character letter for a mode ('i' for insert, 'n' for normal).
+---
+---  For example:
+--- <code>
+---   mappings = {
+---     i = {
+---       ["<esc>"] = require('telescope.actions').close,
+---     },
+---   }
+--- </code>
+---
+--- To disable a keymap, put `[map] = false`<br>
+--- For example:
+--- <code>
+---   {
+---     ...,
+---     ["<C-n>"] = false,
+---     ...,
+---   }
+--- </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
+--- your own function)
+--- <code>
+---   {
+---     ...,
+---     ["<C-i>"] = require('telescope.actions').select_default,
+---     ...,
+---   }
+--- </code>
+---
+---  If the function you want is part of `telescope.actions`, then you can
+---  simply give a string.
+---    For example, the previous option is equivalent to:
+--- <code>
+---   {
+---     ...,
+---     ["<C-i>"] = "select_default",
+---     ...,
+---   }
+--- </code>
+---
+---  You can also add other mappings using tables with `type = "command"`.
+---    For example:
+--- <code>
+---   {
+---     ...,
+---     ["jj"] = { "<esc>", type = "command" },
+---     ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
+---     ...,
+---   }
+--- </code>
+---
+--- You can also add additional options for mappings of any type ("action" and "command").
+---   For example:
+--- <code>
+---   {
+---     ...,
+---     ["<C-j>"] = {
+---       action = actions.move_selection_next,
+---       opts = { nowait = true, silent = true }
+---     },
+---     ...,
+---   }
+--- </code>
+---
+--- There are three main places you can configure |telescope.mappings|. These are
+--- ordered from the lowest priority to the highest priority.
+---
+--- 1. |telescope.defaults.mappings|
+--- 2. In the |telescope.setup()| table, inside a picker with a given name, use the `mappings` key
+--- <code>
+---   require("telescope").setup {
+---     pickers = {
+---       find_files = {
+---         mappings = {
+---           n = {
+---             ["kj"] = "close",
+---           },
+---         },
+---       },
+---     },
+---   }
+--- </code>
+--- 3. `attach_mappings` function for a particular picker.
+--- <code>
+---   require("telescope.builtin").find_files {
+---     attach_mappings = function(_, map)
+---       map("i", "asdf", function(_prompt_bufnr)
+---         print "You typed asdf"
+---       end)
+---       -- needs to return true if you want to map default_mappings and
+---       -- false if not
+---       return true
+---     end,
+---   }
+--- </code>
+---@brief ]]
+
 local a = vim.api
 
 local actions = require "telescope.actions"
@@ -96,25 +217,6 @@ local assign_function = function(prompt_bufnr, func)
   return func_id
 end
 
---[[
-Usage:
-
-mappings.apply_keymap(42, <function>, {
-  n = {
-    ["<leader>x"] = "just do this string",
-
-    ["<CR>"] = function(picker, prompt_bufnr)
-      actions.close_prompt()
-
->     local filename = ...
-      vim.cmd(string.format(":e %s", filename))
-    end,
-  },
-
-  i = {
-  }
-})
---]]
 local telescope_map = function(prompt_bufnr, mode, key_bind, key_func, opts)
   if not key_func then
     return
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index cc9f158..cfec160 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -15,6 +15,7 @@ docs.test = function()
     "./lua/telescope/command.lua",
     "./lua/telescope/builtin/init.lua",
     "./lua/telescope/themes.lua",
+    "./lua/telescope/mappings.lua",
     "./lua/telescope/pickers/layout_strategies.lua",
     "./lua/telescope/config/resolve.lua",
     "./lua/telescope/make_entry.lua",
diff --git a/scripts/minimal_init.vim b/scripts/minimal_init.vim
index 780c0e2..65ac43f 100644
--- a/scripts/minimal_init.vim
+++ b/scripts/minimal_init.vim
@@ -4,3 +4,4 @@ set rtp+=../tree-sitter-lua/
 
 runtime! plugin/plenary.vim
 runtime! plugin/telescope.lua
+runtime! plugin/ts_lua.vim