docs: rewrite readme and add missing config values + builtin opts

lua/telescope/init.lua

@@ -2,6 +2,7 @@ local _extensions = require "telescope._extensions"
 
 local telescope = {}
 
+-- TODO(conni2461): also table of contents for tree-sitter-lua
 -- TODO: Add pre to the works
 -- ---@pre [[
 -- ---@pre ]]
@@ -10,22 +11,68 @@ local telescope = {}
 --- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
 --- filter, find and pick things in Lua.
 ---
+--- Getting started with telescope:
+---   1. Run `:checkhealth telescope` to make sure everything is installed.
+---   2. Evalulate it working with
+---      `:Telescope find_files` or
+---      `:lua require("telescope.builtin").find_files()`
+---   3. Put a `require("telescope").setup() call somewhere in your neovim config.
+---   4. Read |telescope.setup| to check what config keys are available and what you can put inside the setup call
+---   5. Read |telescope.builtin| to check which builtin pickers are offered and what options these implement
+---   6. Profit
+---
 --- <pre>
 --- To find out more:
 --- https://github.com/nvim-telescope/telescope.nvim
 ---
 ---   :h telescope.setup
+---   :h telescope.command
 ---   :h telescope.builtin
+---   :h telescope.themes
 ---   :h telescope.layout
+---   :h telescope.resolve
 ---   :h telescope.actions
+---   :h telescope.actions.state
+---   :h telescope.actions.set
+---   :h telescope.actions.utils
+---   :h telescope.actions.generate
+---   :h telescope.previewers
+---   :h telescope.actions.history
 --- </pre>
 ---@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
+--- Setup function to be run by user. Configures the defaults, pickers and
+--- extensions of telescope.
+---
+--- Usage:
+--- <code>
+--- require('telescope').setup{
+---   defaults = {
+---     -- Default configuration for telescope goes here:
+---     -- config_key = value,
+---     -- ..
+---   },
+---   pickers = {
+---     -- Default configuration for builtin pickers goes here:
+---     -- picker_name = {
+---     --   picker_config_key = value,
+---     --   ...
+---     -- }
+---     -- Now the picker_config_key will be applied every time you call this
+---     -- builtin picker
+---   },
+---   extensions = {
+---     -- Your extension configuration goes here:
+---     -- extension_name = {
+---     --   extension_config_key = value,
+---     -- }
+---     -- please take a look at the readme of the extension you want to configure
+---   }
+--- }
+--- </code>
+---@param opts table: Configuration opts. Keys: defaults, pickers, extensions
 ---@eval { ["description"] = require('telescope').__format_setup_keys() }
 function telescope.setup(opts)
   opts = opts or {}
@@ -56,11 +103,9 @@ end
 telescope.extensions = require("telescope._extensions").manager
 
 telescope.__format_setup_keys = function()
+  local names = require("telescope.config").descriptions_order
   local descriptions = require("telescope.config").descriptions
 
-  local names = vim.tbl_keys(descriptions)
-  table.sort(names)
-
   local result = { "<pre>", "", "Valid keys for {opts.defaults}" }
   for _, name in ipairs(names) do
     local desc = descriptions[name]