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

* 😄

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

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