docs: `make_entry` and `entry_display`

4 files changed, 194 insertions, 5 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 9903ac2..a736d18 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -2007,6 +2007,101 @@ resolver.resolve_anchor_pos()         *telescope.resolve.resolve_anchor_pos()*
 
 
 ================================================================================
+                                                          *telescope.make_entry*
+
+Each picker has a finder made up of two parts, the results which are the data
+to be displayed, and the entry_maker. These entry_makers are functions returned
+from make_entry functions. These will be referrd to as entry_makers in the
+following documentation.
+
+Every entry maker returns a function which accepts the data to be used for an
+entry. This function will return an entry table (or nil, meaning skip this
+entry) which contains of the - following important keys:
+- value any: value key can be anything but still required
+- valid bool: is an optional key because it defaults to true but if the key is
+  set to false it will not be displayed by the picker. (optional)
+- ordinal string: is the text that is used for filtering (required)
+- display string|function: is either a string of the text that is being 
+  displayed or a function receiving the entry at a later stage, when the entry 
+  is actually being displayed. A function can be useful here if complex 
+  calculation have to be done. `make_entry` can also return a second value a
+  highlight array which will then apply to the line. Highlight entry in this
+  array has the following signature `{ { start_col, end_col }, hl_group }` 
+  (required).
+- filename string: will be interpreted by the default `<cr>` action as open
+  this file (optional)
+- bufnr number: will be interpreted by the default `<cr>` action as open this
+  buffer (optional)
+- lnum number: lnum value which will be interpreted by the default `<cr>` 
+  action as a jump to this line (optional)
+- col number: col value which will be interpreted by the default `<cr>` action
+  as a jump to this column (optional)
+
+More information on easier displaying, see |telescope.pickers.entry_display|
+
+TODO: Document something we call `entry_index`
+
+
+================================================================================
+                                               *telescope.pickers.entry_display*
+
+Entry Display is used to format each entry shown in the result panel.
+
+Entry Display create() will give us a function based on the configuration of
+column widths we pass into it. We then can use this function n times to return
+a string based on structured input.
+
+Note that if you call `create()` inside `make_display` it will be called for
+every single entry. So it is suggested to do this outside of `make_display` for
+the best performance.
+
+The create function will use the column widths passed to it in
+configaration.items. Each item in that table is the number of characters in the
+column. It's also possible for the final column to not have a fixed width, this
+will be shown in the configuartion as 'remaining = true'.
+
+An example of this configuration is shown for the buffers picker
+>
+local displayer = entry_display.create {
+  separator = " ",
+  items = {
+    { width = opts.bufnr_width },
+    { width = 4 },
+    { width = icon_width },
+    { remaining = true },
+  },
+}
+<
+
+This shows 4 columns, the first is defined in the opts as the width we'll use
+when display_string the number of the buffer. The second has a fixed width of 4
+and the 3rd column's widht will be decided by the width of the icons we use.
+The fourth column will use the remaining space. Finally we have also defined
+the seperator between each column will be the space " ".
+
+An example of how the display reference will be used is shown, again for the
+buffers picker:
+>
+return displayer {
+  { entry.bufnr, "TelescopeResultsNumber" },
+  { entry.indicator, "TelescopeResultsComment" },
+  { icon, hl_group },
+  display_bufname .. ":" .. entry.lnum,
+}
+<
+
+There are two types of values each column can have. Either a simple String or a
+table containing the String as well as the hl_group.
+
+The displayer can return values, string and an optional highlights. String is
+all the text to be displayed for this entry as a single string. If parts of the
+string are to be highlighted they will be described in the highlights table.
+
+For better understanding of how create() and displayer are used it's best to
+look at the code in make_entry.lua.
+
+
+================================================================================
                                                                *telescope.utils*
 
 Utilities for writing telescope pickers
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index e8f2509..64993df 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -1,3 +1,40 @@
+---@tag telescope.make_entry
+
+---@brief [[
+---
+--- Each picker has a finder made up of two parts, the results which are the
+--- data to be displayed, and the entry_maker. These entry_makers are functions
+--- returned from make_entry functions. These will be referrd to as
+--- entry_makers in the following documentation.
+---
+--- Every entry maker returns a function which accepts the data to be used for
+--- an entry. This function will return an entry table (or nil, meaning skip
+--- this entry) which contains of the - following important keys:
+--- - value any: value key can be anything but still required
+--- - valid bool: is an optional key because it defaults to true but if the key
+---   is set to false it will not be displayed by the picker. (optional)
+--- - ordinal string: is the text that is used for filtering (required)
+--- - display string|function: is either a string of the text that is being
+---   displayed or a function receiving the entry at a later stage, when the entry
+---   is actually being displayed. A function can be useful here if complex
+---   calculation have to be done. `make_entry` can also return a second value
+---   a highlight array which will then apply to the line. Highlight entry in
+---   this array has the following signature `{ { start_col, end_col }, hl_group }`
+---   (required).
+--- - filename string: will be interpreted by the default `<cr>` action as
+---   open this file (optional)
+--- - bufnr number: will be interpreted by the default `<cr>` action as open
+---   this buffer (optional)
+--- - lnum number: lnum value which will be interpreted by the default `<cr>`
+---   action as a jump to this line (optional)
+--- - col number: col value which will be interpreted by the default `<cr>`
+---   action as a jump to this column (optional)
+---
+--- More information on easier displaying, see |telescope.pickers.entry_display|
+---
+--- TODO: Document something we call `entry_index`
+---@brief ]]
+
 local entry_display = require "telescope.pickers.entry_display"
 local utils = require "telescope.utils"
 local strings = require "plenary.strings"
@@ -190,9 +227,6 @@ do
     return { filename, lnum, col, text }
   end
 
-  --- Special options:
-  ---  - disable_coordinates: Don't show the line & row numbers
-  ---  - only_sort_text: Only sort via the text. Ignore filename and other items
   function make_entry.gen_from_vimgrep(opts)
     local mt_vimgrep_entry
 
@@ -919,8 +953,6 @@ function make_entry.gen_from_vimoptions(opts)
   end
 end
 
---- Special options:
----  - only_sort_tags: Only sort via tag name. Ignore filename and other items
 function make_entry.gen_from_ctags(opts)
   opts = opts or {}
 
diff --git a/lua/telescope/pickers/entry_display.lua b/lua/telescope/pickers/entry_display.lua
index b1a1473..6e520f4 100644
--- a/lua/telescope/pickers/entry_display.lua
+++ b/lua/telescope/pickers/entry_display.lua
@@ -1,3 +1,63 @@
+---@tag telescope.pickers.entry_display
+
+---@brief [[
+--- Entry Display is used to format each entry shown in the result panel.
+---
+--- Entry Display create() will give us a function based on the configuration
+--- of column widths we pass into it. We then can use this function n times to
+--- return a string based on structured input.
+---
+--- Note that if you call `create()` inside `make_display` it will be called for
+--- every single entry. So it is suggested to do this outside of `make_display`
+--- for the best performance.
+---
+--- The create function will use the column widths passed to it in
+--- configaration.items. Each item in that table is the number of characters in
+--- the column. It's also possible for the final column to not have a fixed
+--- width, this will be shown in the configuartion as 'remaining = true'.
+---
+--- An example of this configuration is shown for the buffers picker
+--- <code>
+--- local displayer = entry_display.create {
+---   separator = " ",
+---   items = {
+---     { width = opts.bufnr_width },
+---     { width = 4 },
+---     { width = icon_width },
+---     { remaining = true },
+---   },
+--- }
+--- </code>
+---
+--- This shows 4 columns, the first is defined in the opts as the width we'll
+--- use when display_string the number of the buffer. The second has a fixed
+--- width of 4 and the 3rd column's widht will be decided by the width of the
+--- icons we use. The fourth column will use the remaining space. Finally we
+--- have also defined the seperator between each column will be the space " ".
+---
+--- An example of how the display reference will be used is shown, again for
+--- the buffers picker:
+--- <code>
+--- return displayer {
+---   { entry.bufnr, "TelescopeResultsNumber" },
+---   { entry.indicator, "TelescopeResultsComment" },
+---   { icon, hl_group },
+---   display_bufname .. ":" .. entry.lnum,
+--- }
+--- </code>
+---
+--- There are two types of values each column can have. Either a simple String
+--- or a table containing the String as well as the hl_group.
+---
+--- The displayer can return values, string and an optional highlights.
+--- String is all the text to be displayed for this entry as a single string. If
+--- parts of the string are to be highlighted they will be described in the
+--- highlights table.
+---
+--- For better understanding of how create() and displayer are used it's best to look
+--- at the code in make_entry.lua.
+---@brief ]]
+
 local strings = require "plenary.strings"
 local state = require "telescope.state"
 local resolve = require "telescope.config.resolve"
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 524cb04..cc9f158 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -17,6 +17,8 @@ docs.test = function()
     "./lua/telescope/themes.lua",
     "./lua/telescope/pickers/layout_strategies.lua",
     "./lua/telescope/config/resolve.lua",
+    "./lua/telescope/make_entry.lua",
+    "./lua/telescope/pickers/entry_display.lua",
     "./lua/telescope/utils.lua",
     "./lua/telescope/actions/init.lua",
     "./lua/telescope/actions/state.lua",