feat: Add vim docs & generators (#370)

* feat: Add vim docs & generators

* example of what we could start to do

* Docgen CI job

* wip

* incremental updates. soon good validation

* [Actions] Generate Documentation
skip-checks: true

* pretty cool now

* [Actions] Generate Documentation
skip-checks: true

* make sure telescope is loaded first

* Add updates. Maybe this will not delete now?

* Add defaults tags as well

* :smile:

Co-authored-by: Simon Hauser <Simon-Hauser@outlook.de>
Co-authored-by: Github Actions <actions@github>

4 files changed, 173 insertions, 79 deletions

diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 304e9f1..a625ac1 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -1,15 +1,17 @@
---[[
-A collection of builtin pipelines for telesceope.
+---@tag telescope.builtin
 
-Meant for both example and for easy startup.
-
-Any of these functions can just be called directly by doing:
-
-:lua require('telescope.builtin').__name__()
-
-This will use the default configuration options.
-  Other configuration options still in flux at the moment
---]]
+---@brief [[
+--- A collection of builtin pickers for telesceope.
+---
+--- Meant for both example and for easy startup.
+---
+--- Any of these functions can just be called directly by doing:
+---
+--- :lua require('telescope.builtin').$NAME()
+---
+--- This will use the default configuration options.
+---   Other configuration options are still in flux at the moment
+---@brief ]]
 
 if 1 ~= vim.fn.has('nvim-0.5') then
   vim.api.nvim_err_writeln("This plugins requires neovim 0.5")
@@ -19,7 +21,9 @@ end
 
 local builtin = {}
 
+--- Live grep means grep as you type.
 builtin.live_grep = require('telescope.builtin.files').live_grep
+
 builtin.grep_string = require('telescope.builtin.files').grep_string
 builtin.find_files = require('telescope.builtin.files').find_files
 builtin.fd = builtin.find_files
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index 30526e5..9b749ed 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -20,6 +20,7 @@ local sorters = require('telescope.sorters')
 local config = {}
 
 config.values = _TelescopeConfigurationValues
+config.descriptions = {}
 
 function config.set_defaults(defaults)
   defaults = defaults or {}
@@ -28,13 +29,40 @@ function config.set_defaults(defaults)
     return first_non_null(defaults[name], config.values[name], default_val)
   end
 
-  local function set(name, default_val)
+  local function set(name, default_val, description)
+    -- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
+    -- assert(description, "Config values must always have a description")
+
     config.values[name] = get(name, default_val)
+    if description then
+      config.descriptions[name] = vim.trim(description)
+    end
   end
 
-  set("sorting_strategy", "descending")
-  set("selection_strategy", "reset")
-  set("scroll_strategy", "cycle")
+  set("sorting_strategy", "descending", [[
+    Determines the direction "better" results are sorted towards.
+
+      Available options are:
+      - "descending" (default)
+      - "ascending"
+  ]])
+
+  set("selection_strategy", "reset", [[
+    Determines how the cursor acts after each sort iteration.
+
+      Available options are:
+      - "reset" (default)
+      - "follow"
+      - "row"
+  ]])
+
+  set("scroll_strategy", "cycle", [[
+    Determines what happens you try to scroll past view of the picker.
+
+      Available options are:
+      - "cycle" (default)
+      - "limit"
+  ]])
 
   set("layout_strategy", "horizontal")
   set("layout_defaults", {})
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 6fcb76b..2269efe 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -4,6 +4,30 @@ local _extensions = require('telescope._extensions')
 
 local telescope = {}
 
+-- TODO: Add pre to the works
+-- ---@pre [[
+-- ---@pre ]]
+
+---@brief [[
+--- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
+--- filter, find and pick things in Lua.
+---
+--- To find out more:
+--- https://github.com/nvim-telescope/telescope.nvim
+--
+--   :h telescope.setup
+--   :h telescope.builtin
+--   :h telescope.layout
+--   :h telescope.actions
+--
+---@brief ]]
+
+---@tag telescope.nvim
+
+--- Setup function to be run by user. Configures the defaults, extensions
+--- and other aspects of telescope.
+---@param opts table: Configuration opts. Keys: defaults, extensions
+---@eval { ["description"] = require('telescope').__format_setup_keys() }
 function telescope.setup(opts)
   opts = opts or {}
 
@@ -15,15 +39,39 @@ function telescope.setup(opts)
   _extensions.set_config(opts.extensions)
 end
 
+--- Register an extension. To be used by plugin authors.
+---@param mod table: Module
 function telescope.register_extension(mod)
   return _extensions.register(mod)
 end
 
+--- Load an extension.
+---@param name string: Name of the extension
 function telescope.load_extension(name)
   return _extensions.load(name)
 end
 
 --- Use telescope.extensions to reference any extensions within your configuration.
+--- While the docs currently generate this as a function, it's actually a table. Sorry.
 telescope.extensions = require('telescope._extensions').manager
 
+telescope.__format_setup_keys = function()
+  local descriptions = require('telescope.config').descriptions
+
+  local names = vim.tbl_keys(descriptions)
+  table.sort(names)
+
+  local result = { "", "", "Valid keys for {opts.defaults}" }
+  for _, name in ipairs(names) do
+    local desc = descriptions[name]
+
+    table.insert(result, "")
+    table.insert(result, string.format("%s*telescope.defaults.%s*", string.rep(" ", 70 - 20 - #name), name))
+    table.insert(result, string.format("%s: ~", name))
+    table.insert(result, string.format("    %s", desc))
+  end
+
+  return result
+end
+
 return telescope
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index 334ac2f..382d9a6 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -1,28 +1,39 @@
---[[
-
-Layout strategies are different functions to position telescope.
-
-horizontal:
-- Supports `prompt_position`, `preview_cutoff`
-
-vertical:
-
-flex: Swap between `horizontal` and `vertical` strategies based on the window width
-- Supports `vertical` or `horizontal` features
-
-dropdown:
-
-
-Layout strategies are callback functions
-
--- @param self: Picker
--- @param columns: number Columns in the vim window
--- @param lines: number Lines in the vim window
-
-function(self, columns, lines)
-end
-
---]]
+---@tag telescope.layout
+
+---@brief [[
+---
+--- Layout strategies are different functions to position telescope.
+---
+--- All layout strategies are functions with the following signature: >
+---
+---      function(picker, columns, lines)
+---        -- Do some calculations here...
+---        return {
+---          preview = preview_configuration
+---          results = results_configuration,
+---          prompt = prompt_configuration,
+---        }
+---      end
+--- <
+---
+---     Parameters: ~
+---         - picker  : A Picker object. (docs coming soon)
+---         - columns : number Columns in the vim window
+---         - lines   : number Lines in the vim window
+---
+--- TODO: I would like to make these link to `telescope.layout_strategies.*`, but it's not yet possible.
+---
+--- Available layout strategies include:
+---   horizontal:
+---   - See |layout_strategies.horizontal|
+---
+---   vertical:
+---   - See |layout_strategies.vertical|
+---
+---   flex:
+---   - See |layout_strategies.flex|
+---
+---@brief ]]
 
 local config = require('telescope.config')
 local resolve = require("telescope.config.resolve")
@@ -50,16 +61,16 @@ end
 
 local layout_strategies = {}
 
---[[
-   +-----------------+---------------------+
-   |                 |                     |
-   |     Results     |                     |
-   |                 |       Preview       |
-   |                 |                     |
-   +-----------------|                     |
-   |     Prompt      |                     |
-   +-----------------+---------------------+
---]]
+--- Horizontal previewer
+---
+---   +-------------+--------------+
+---   |             |              |
+---   |   Results   |              |
+---   |             |    Preview   |
+---   |             |              |
+---   +-------------|              |
+---   |   Prompt    |              |
+---   +-------------+--------------+
 layout_strategies.horizontal = function(self, max_columns, max_lines)
   local layout_config = validate_layout_config(self.layout_config or {}, {
     width_padding = "How many cells to pad the width",
@@ -144,19 +155,18 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
 }
 end
 
---[[
-    +--------------+
-    |    Preview   |
-    +--------------+
-    |    Prompt    |
-    +--------------+
-    |    Result    |
-    |    Result    |
-    |    Result    |
-    +--------------+
-
-
---]]
+--- Centered layout wih smaller default sizes (I think)
+---
+---    +--------------+
+---    |    Preview   |
+---    +--------------+
+---    |    Prompt    |
+---    +--------------+
+---    |    Result    |
+---    |    Result    |
+---    |    Result    |
+---    +--------------+
+---
 layout_strategies.center = function(self, columns, lines)
   local initial_options = self:_get_initial_window_options()
   local preview = initial_options.preview
@@ -204,19 +214,20 @@ layout_strategies.center = function(self, columns, lines)
   }
 end
 
---[[
-    +-----------------+
-    |    Previewer    |
-    |    Previewer    |
-    |    Previewer    |
-    +-----------------+
-    |     Result      |
-    |     Result      |
-    |     Result      |
-    +-----------------+
-    |     Prompt      |
-    +-----------------+
---]]
+--- Vertical perviewer stacks the items on top of each other.
+---
+---    +-----------------+
+---    |    Previewer    |
+---    |    Previewer    |
+---    |    Previewer    |
+---    +-----------------+
+---    |     Result      |
+---    |     Result      |
+---    |     Result      |
+---    +-----------------+
+---    |     Prompt      |
+---    +-----------------+
+---
 layout_strategies.vertical = function(self, max_columns, max_lines)
   local layout_config = self.layout_config or {}
   local initial_options = self:_get_initial_window_options()
@@ -276,9 +287,12 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
   }
 end
 
--- Uses:
---  flip_columns
---  flip_lines
+--- Swap between `horizontal` and `vertical` strategies based on the window width
+---   -  Supports `vertical` or `horizontal` features
+---
+---   Uses:
+---    flip_columns
+---    flip_lines
 layout_strategies.flex = function(self, max_columns, max_lines)
   local layout_config = self.layout_config or {}