From 9dca53acd55d59267f2661b988562c5279d5e0eb Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Tue, 1 Dec 2020 12:13:46 -0500
Subject: [PATCH 01/12] feat: Add vim docs & generators

---
 docs/telescope.txt     | 34 ++++++++++++++++++++++++++++++++++
 lua/telescope/docs.lua | 27 +++++++++++++++++++++++++++
 lua/telescope/init.lua | 18 ++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 docs/telescope.txt
 create mode 100644 lua/telescope/docs.lua

diff --git a/docs/telescope.txt b/docs/telescope.txt
new file mode 100644
index 0000000000..8eefbad11e
--- /dev/null
+++ b/docs/telescope.txt
@@ -0,0 +1,34 @@
+================================================================================
+                                                                *telescope.nvim*
+
+Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search
+for anything you can imagine (and then write in Lua).
+
+telescope.setup({opts})                                    *telescope.setup()*
+        and other aspects of telescope.
+
+        Parameters: ~
+            {opts} (table)  Configuration opts. Keys: defaults, extensions
+
+
+telescope.load_extension({name})                  *telescope.load_extension()*
+        Load an extension.
+
+        Parameters: ~
+            {name} (string)  Name of the extension
+
+
+telescope.register_extension({mod})           *telescope.register_extension()*
+        Register an extension. To be used by plugin authors.
+
+        Parameters: ~
+            {mod} (table)  Module
+
+
+telescope.extensions()                                *telescope.extensions()*
+        While the docs currently generate this as a function, it's actually a
+        table. Sorry.
+
+
+
+ vim:tw=78:ts=8:ft=help:norl:
\ No newline at end of file
diff --git a/lua/telescope/docs.lua b/lua/telescope/docs.lua
new file mode 100644
index 0000000000..61f29c48c1
--- /dev/null
+++ b/lua/telescope/docs.lua
@@ -0,0 +1,27 @@
+RELOAD('docgen')
+
+local docgen = require('docgen')
+
+local docs = {}
+
+docs.test = function()
+  local input_dir = "./lua/telescope/"
+  local input_files = vim.fn.globpath(input_dir, "**/*.lua", false, true)
+
+  input_files = { "./lua/telescope/init.lua" }
+
+  local output_file = "./docs/telescope.txt"
+  local output_file_handle = io.open(output_file, "w")
+
+  for _, input_file in ipairs(input_files) do
+    docgen.write(input_file, output_file_handle)
+  end
+
+  output_file_handle:write(" vim:tw=78:ts=8:ft=help:norl:")
+  output_file_handle:close()
+  vim.cmd [[checktime]]
+end
+
+docs.test()
+
+return docs
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 6fcb76b14e..2b80555c49 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -4,6 +4,19 @@ 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
+--- for anything you can imagine (and then write in Lua).
+---@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
 function telescope.setup(opts)
   opts = opts or {}
 
@@ -15,15 +28,20 @@ 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
 
 return telescope

From 16730804d78660814faa280fcad89732df9b848c Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Mon, 11 Jan 2021 16:33:19 -0500
Subject: [PATCH 02/12] example of what we could start to do

---
 docs/telescope.txt     | 31 +++++++++++++++++++++----------
 lua/telescope/docs.lua |  9 ++++++++-
 lua/telescope/init.lua |  8 ++++++--
 3 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/docs/telescope.txt b/docs/telescope.txt
index 8eefbad11e..c4aeea9f6a 100644
--- a/docs/telescope.txt
+++ b/docs/telescope.txt
@@ -1,14 +1,14 @@
 ================================================================================
                                                                 *telescope.nvim*
 
-Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search
-for anything you can imagine (and then write in Lua).
+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
 
-telescope.setup({opts})                                    *telescope.setup()*
-        and other aspects of telescope.
-
-        Parameters: ~
-            {opts} (table)  Configuration opts. Keys: defaults, extensions
+telescope.extensions()                                *telescope.extensions()*
+        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.load_extension({name})                  *telescope.load_extension()*
@@ -25,9 +25,20 @@ telescope.register_extension({mod})           *telescope.register_extension()*
             {mod} (table)  Module
 
 
-telescope.extensions()                                *telescope.extensions()*
-        While the docs currently generate this as a function, it's actually a
-        table. Sorry.
+telescope.setup({opts})                                    *telescope.setup()*
+        Setup function to be run by user. Configures the defaults, extensions
+        and other aspects of telescope. Valid keys:
+        { "layout_defaults",
+        "use_less", "results_height", "selection_strategy", "sorting_strategy",
+        "results_width", "get_status_text", "buffer_previewer_maker",
+        "prompt_position", "color_devicons", "vimgrep_arguments", "border",
+        "qflist_previewer", "width", "grep_previewer", "file_previewer",
+        "generic_sorter", "borderchars", "winblend", "mappings",
+        "scroll_strategy", "set_env", "prompt_prefix", "file_sorter",
+        "preview_cutoff", "layout_strategy" }
+
+        Parameters: ~
+            {opts} (table)  Configuration opts. Keys: defaults, extensions
 
 
 
diff --git a/lua/telescope/docs.lua b/lua/telescope/docs.lua
index 61f29c48c1..02cdb8cb31 100644
--- a/lua/telescope/docs.lua
+++ b/lua/telescope/docs.lua
@@ -8,7 +8,14 @@ docs.test = function()
   local input_dir = "./lua/telescope/"
   local input_files = vim.fn.globpath(input_dir, "**/*.lua", false, true)
 
-  input_files = { "./lua/telescope/init.lua" }
+  -- TODO: Fix the other files so that we can add them here.
+  input_files = {
+    "./lua/telescope/init.lua"
+  }
+
+  table.sort(input_files, function(a, b)
+    return #a < #b
+  end)
 
   local output_file = "./docs/telescope.txt"
   local output_file_handle = io.open(output_file, "w")
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 2b80555c49..01e892814c 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -9,14 +9,18 @@ local telescope = {}
 -- ---@pre ]]
 
 ---@brief [[
---- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search
---- for anything you can imagine (and then write in Lua).
+--- 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
 ---@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"] =  'Valid keys:\n' .. vim.inspect(vim.tbl_keys(require('telescope.config').values)) }
 function telescope.setup(opts)
   opts = opts or {}
 

From 21da47d3867a1b6a4c62a9f8c003e17a6ad12d9f Mon Sep 17 00:00:00 2001
From: Simon Hauser <Simon-Hauser@outlook.de>
Date: Wed, 20 Jan 2021 22:04:01 +0100
Subject: [PATCH 03/12] Docgen CI job

---
 .github/workflows/docgen.yml                  | 70 +++++++++++++++++++
 .gitignore                                    |  1 +
 Makefile                                      |  3 +
 {docs => doc}/telescope.txt                   |  0
 lua/telescope/docs.lua => scripts/gendocs.lua |  9 +--
 scripts/minimal_init.vim                      |  1 +
 6 files changed, 78 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/docgen.yml
 rename {docs => doc}/telescope.txt (100%)
 rename lua/telescope/docs.lua => scripts/gendocs.lua (67%)

diff --git a/.github/workflows/docgen.yml b/.github/workflows/docgen.yml
new file mode 100644
index 0000000000..ec7d8c934c
--- /dev/null
+++ b/.github/workflows/docgen.yml
@@ -0,0 +1,70 @@
+name: Generate docs
+
+on: push
+
+jobs:
+  build-sources:
+    name: Generate docs
+    runs-on: ubuntu-20.04
+    if: github.ref != 'master'
+    steps:
+      - uses: actions/checkout@v2
+      - run: date +%F > todays-date
+      - name: Restore cache for today's nightly.
+        uses: actions/cache@v2
+        with:
+          path: build
+          key: ${{ runner.os }}-appimage-${{ hashFiles('todays-date') }}
+
+      - name: Restore cache for tree-sitter
+        uses: actions/cache@v2
+        with:
+          path: _ts
+          key: ${{ runner.os }}-ts-${{ hashFiles('todays-date') }}
+
+      - name: Prepare
+        run: |
+          test -d build || {
+            mkdir -p build
+            wget https://github.com/neovim/neovim/releases/download/nightly/nvim.appimage
+            chmod +x nvim.appimage
+            mv nvim.appimage ./build/nvim
+          }
+          test -d _ts || {
+            # Pining version. Not sure if we should actually do that
+            mkdir -p _ts
+            wget https://github.com/tree-sitter/tree-sitter/releases/download/0.17.3/tree-sitter-linux-x64.gz
+            gzip -d tree-sitter-linux-x64
+            chmod +x tree-sitter-linux-x64
+            mv tree-sitter-linux-x64 ./_ts/tree-sitter
+          }
+          mkdir -p ~/.local/share/nvim/site/pack/vendor/start
+          git clone --depth 1 https://github.com/tjdevries/tree-sitter-lua ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
+          ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start
+
+      - name: Build parser
+        run: |
+          # We have to build the parser every single time to keep up with parser changes
+          export PATH="${PWD}/_ts/:${PATH}"
+          cd ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
+          mkdir -p build parser
+          make build_parser
+          ln -s ../build/parser.so parser/lua.so
+          cd
+
+      # inspired by nvim-lspconfigs
+      - name: Generating docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMIT_MSG: |
+            [Actions] Generate Documentation
+            skip-checks: true
+        run: |
+          export PATH="${PWD}/build/:${PATH}"
+          git config user.email "actions@github"
+          git config user.name "Github Actions"
+          git remote set-url origin https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
+          make docgen
+          git add doc/
+          # Only commit and push if we have changes
+          git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push origin HEAD:${GITHUB_REF})
diff --git a/.gitignore b/.gitignore
index 567609b123..6799a850a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 build/
+doc/tags
diff --git a/Makefile b/Makefile
index 2da1c220c1..c3da51def6 100644
--- a/Makefile
+++ b/Makefile
@@ -3,3 +3,6 @@ test:
 
 lint:
 	luacheck lua/telescope
+
+docgen:
+	nvim --headless --noplugin -u scripts/minimal_init.vim -c "luafile ./scripts/gendocs.lua" -c 'qa'
diff --git a/docs/telescope.txt b/doc/telescope.txt
similarity index 100%
rename from docs/telescope.txt
rename to doc/telescope.txt
diff --git a/lua/telescope/docs.lua b/scripts/gendocs.lua
similarity index 67%
rename from lua/telescope/docs.lua
rename to scripts/gendocs.lua
index 02cdb8cb31..03a35ce1a6 100644
--- a/lua/telescope/docs.lua
+++ b/scripts/gendocs.lua
@@ -5,11 +5,8 @@ local docgen = require('docgen')
 local docs = {}
 
 docs.test = function()
-  local input_dir = "./lua/telescope/"
-  local input_files = vim.fn.globpath(input_dir, "**/*.lua", false, true)
-
   -- TODO: Fix the other files so that we can add them here.
-  input_files = {
+  local input_files = {
     "./lua/telescope/init.lua"
   }
 
@@ -17,14 +14,14 @@ docs.test = function()
     return #a < #b
   end)
 
-  local output_file = "./docs/telescope.txt"
+  local output_file = "./doc/telescope.txt"
   local output_file_handle = io.open(output_file, "w")
 
   for _, input_file in ipairs(input_files) do
     docgen.write(input_file, output_file_handle)
   end
 
-  output_file_handle:write(" vim:tw=78:ts=8:ft=help:norl:")
+  output_file_handle:write(" vim:tw=78:ts=8:ft=help:norl:\n")
   output_file_handle:close()
   vim.cmd [[checktime]]
 end
diff --git a/scripts/minimal_init.vim b/scripts/minimal_init.vim
index 1d4c7b13c2..97d3996c9d 100644
--- a/scripts/minimal_init.vim
+++ b/scripts/minimal_init.vim
@@ -1,6 +1,7 @@
 set rtp+=.
 set rtp+=../plenary.nvim/
 set rtp+=../popup.nvim/
+set rtp+=../tree-sitter-lua/
 
 runtime! plugin/plenary.vim
 runtime! plugin/telescope.vim

From 7c90fdd6228c77ea7683d9ea17f3b99d09989104 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Tue, 23 Feb 2021 22:03:23 -0500
Subject: [PATCH 04/12] wip

---
 CONTRIBUTING.md                | 48 +++++++++++++++++++++++++++++++
 doc/telescope.txt              | 52 +++++++++++++++++++++++-----------
 lua/telescope/builtin/init.lua | 26 ++++++++++-------
 lua/telescope/init.lua         |  5 ++++
 scripts/gendocs.lua            |  8 ++++--
 5 files changed, 108 insertions(+), 31 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..7ad008d03f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Documentation
+
+is generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation will be exported that is part of the returning module. So example:
+
+local m = {}
+
+--- Test Header
+--@return 1: Returns always 1
+function m.a()
+  return 1
+end
+
+return m
+
+Something like this.
+What is missing?
+
+The docgen has some problems on which people can work. This would happen in https://github.com/tjdevries/tree-sitter-lua and documentation of some modules here.
+I would suggest we are documenting lua/telescope/builtin/init.lua rather than the files itself. We can use that init.lua file as "header" file, so we are not cluttering the other files.
+How to do it:
+
+
+## Auto-updates from CI
+
+The easy way would be after this PR is merged
+
+    write some docs
+    commit and push
+    wait a minute until the CI generates a new commit with the changes
+    Look at this commit and the changes
+    And apply new changes with git commit --amend and git push --force to remove that github ci commit again.
+    Repeat until done
+
+## Generate on your local machine
+
+The other option would be setting up https://github.com/tjdevries/tree-sitter-lua
+
+    Install Treesitter, either with package manager or with github release
+    Install plugin as usual
+    cd to plugin
+    mkdir -p build parser Sadly does doesn't exist laughing
+    make build_parser
+    ln -s ../build/parser.so parser/lua.so We need the so in parser/ so it gets picked up by neovim. Either copy or symbolic link
+    Make sure that nvim-treesitter lua parser is not installed and also delete the lua queries in that repository. queries/lua/*. If you are not doing that you will have a bad time
+    cd into this project
+    Write doc
+    Run make docgen
+    Repeat last two steps
diff --git a/doc/telescope.txt b/doc/telescope.txt
index c4aeea9f6a..38462b114c 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -2,44 +2,62 @@
                                                                 *telescope.nvim*
 
 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:
+filter, find and pick things in Lua.
+
+To find out more:
 https://github.com/nvim-telescope/telescope.nvim
 
 telescope.extensions()                                *telescope.extensions()*
-        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.load_extension({name})                  *telescope.load_extension()*
-        Load an extension.
+        
 
         Parameters: ~
             {name} (string)  Name of the extension
 
 
 telescope.register_extension({mod})           *telescope.register_extension()*
-        Register an extension. To be used by plugin authors.
+        
 
         Parameters: ~
             {mod} (table)  Module
 
 
 telescope.setup({opts})                                    *telescope.setup()*
-        Setup function to be run by user. Configures the defaults, extensions
-        and other aspects of telescope. Valid keys:
-        { "layout_defaults",
-        "use_less", "results_height", "selection_strategy", "sorting_strategy",
-        "results_width", "get_status_text", "buffer_previewer_maker",
-        "prompt_position", "color_devicons", "vimgrep_arguments", "border",
-        "qflist_previewer", "width", "grep_previewer", "file_previewer",
-        "generic_sorter", "borderchars", "winblend", "mappings",
-        "scroll_strategy", "set_env", "prompt_prefix", "file_sorter",
-        "preview_cutoff", "layout_strategy" }
+        Valid keys:
+        { "prompt_position", "generic_sorter",
+        "preview_cutoff", "results_height", "results_width", "prompt_prefix",
+        "initial_mode", "borderchars", "winblend", "qflist_previewer",
+        "buffer_previewer_maker", "get_status_text", "grep_previewer",
+        "file_previewer", "file_sorter", "vimgrep_arguments", "mappings",
+        "border", "sorting_strategy", "color_devicons", "selection_strategy",
+        "width", "scroll_strategy", "use_less", "layout_strategy",
+        "layout_defaults" }
 
         Parameters: ~
             {opts} (table)  Configuration opts. Keys: defaults, extensions
 
 
 
- vim:tw=78:ts=8:ft=help:norl:
\ No newline at end of file
+================================================================================
+                                                             *telescope.builtin*
+
+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
+
+builtin.live_grep()                                      *builtin.live_grep()*
+        
+
+
+
+ vim:tw=78:ts=8:ft=help:norl:
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 304e9f1d03..986356c6ef 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/init.lua b/lua/telescope/init.lua
index 01e892814c..5d364038ac 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -14,7 +14,12 @@ local telescope = {}
 ---
 --- 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
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 03a35ce1a6..ee4db02ad5 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -1,13 +1,15 @@
-RELOAD('docgen')
-
 local docgen = require('docgen')
 
 local docs = {}
 
+--- Wowow
+---@param hello number|table: hello?
+---@eval {["hello"] = 5}
 docs.test = function()
   -- TODO: Fix the other files so that we can add them here.
   local input_files = {
-    "./lua/telescope/init.lua"
+    "./lua/telescope/init.lua",
+    "./lua/telescope/builtin/init.lua",
   }
 
   table.sort(input_files, function(a, b)

From e4df1425c10fe151bb39d69a383288cecf6a72b1 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Tue, 23 Feb 2021 23:12:10 -0500
Subject: [PATCH 05/12] incremental updates. soon good validation

---
 doc/telescope.txt        | 40 +++++++++++++++++++++++++++-------------
 lua/telescope/config.lua | 22 +++++++++++++++++++---
 lua/telescope/init.lua   | 24 +++++++++++++++++++++++-
 3 files changed, 69 insertions(+), 17 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 38462b114c..536207ef06 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -8,33 +8,47 @@ To find out more:
 https://github.com/nvim-telescope/telescope.nvim
 
 telescope.extensions()                                *telescope.extensions()*
-        
+        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.load_extension({name})                  *telescope.load_extension()*
-        
+        Load an extension.
 
         Parameters: ~
             {name} (string)  Name of the extension
 
 
 telescope.register_extension({mod})           *telescope.register_extension()*
-        
+        Register an extension. To be used by plugin authors.
 
         Parameters: ~
             {mod} (table)  Module
 
 
 telescope.setup({opts})                                    *telescope.setup()*
-        Valid keys:
-        { "prompt_position", "generic_sorter",
-        "preview_cutoff", "results_height", "results_width", "prompt_prefix",
-        "initial_mode", "borderchars", "winblend", "qflist_previewer",
-        "buffer_previewer_maker", "get_status_text", "grep_previewer",
-        "file_previewer", "file_sorter", "vimgrep_arguments", "mappings",
-        "border", "sorting_strategy", "color_devicons", "selection_strategy",
-        "width", "scroll_strategy", "use_less", "layout_strategy",
-        "layout_defaults" }
+        Setup function to be run by user. Configures the defaults, extensions
+
+        and other aspects of telescope.
+        Valid Setup Keys:
+
+
+selection_strategy:
+    nevermind, read the source
+        code.
+
+
+sorting_strategy:
+    Sorting strategy determines the direction
+        "better" results are sorted towards.
+
+      Available options are:
+     
+        - "descending"
+      - "ascending"
+
 
         Parameters: ~
             {opts} (table)  Configuration opts. Keys: defaults, extensions
@@ -56,7 +70,7 @@ This will use the default configuration options.
   Other configuration options are still in flux at the moment
 
 builtin.live_grep()                                      *builtin.live_grep()*
-        
+        Live grep means grep as you type.
 
 
 
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index 30526e5247..ac2693eaca 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,12 +29,27 @@ 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)
+    -- 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("sorting_strategy", "descending", [[
+    Sorting strategy determines the direction "better" results are sorted towards.
+
+      Available options are:
+      - "descending"
+      - "ascending"
+  ]])
+
+  set("selection_strategy", "reset", [[
+    nevermind, read the source code.
+  ]])
+
   set("scroll_strategy", "cycle")
 
   set("layout_strategy", "horizontal")
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 5d364038ac..2aa95195cc 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -25,7 +25,7 @@ local telescope = {}
 --- 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"] =  'Valid keys:\n' .. vim.inspect(vim.tbl_keys(require('telescope.config').values)) }
+---@eval { ["description"] = require('telescope').__format_setup_keys() }
 function telescope.setup(opts)
   opts = opts or {}
 
@@ -53,4 +53,26 @@ end
 --- 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()
+  -- return 'Valid keys:\n' .. vim.inspect(vim.tbl_keys(require('telescope.config').values)) 
+
+  local result = "Valid Setup Keys:\n"
+
+  local descriptions = require('telescope.config').descriptions
+
+  local names = vim.tbl_keys(descriptions)
+  table.sort(names)
+
+  for _, name in ipairs(names) do
+    local desc = descriptions[name]
+
+    -- hint: make sure you're considering UNICODE?!?!?!?
+    result = result .. "\n"
+      .. string.format("\n%s:\n", name)
+      .. string.format("    %s\n", desc)
+  end
+
+  return result
+end
+
 return telescope

From d61c21fe1d15ca9a500df8e80da623f441c393c8 Mon Sep 17 00:00:00 2001
From: Github Actions <actions@github>
Date: Wed, 24 Feb 2021 04:14:24 +0000
Subject: [PATCH 06/12] [Actions] Generate Documentation skip-checks: true

---
 doc/telescope.txt | 17 -----------------
 1 file changed, 17 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 536207ef06..2fa78e8d2c 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -32,23 +32,6 @@ telescope.setup({opts})                                    *telescope.setup()*
         Setup function to be run by user. Configures the defaults, extensions
 
         and other aspects of telescope.
-        Valid Setup Keys:
-
-
-selection_strategy:
-    nevermind, read the source
-        code.
-
-
-sorting_strategy:
-    Sorting strategy determines the direction
-        "better" results are sorted towards.
-
-      Available options are:
-     
-        - "descending"
-      - "ascending"
-
 
         Parameters: ~
             {opts} (table)  Configuration opts. Keys: defaults, extensions

From fe1c531de5d5143038a2ea29ece8793d0b92fd57 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 24 Feb 2021 16:11:14 -0500
Subject: [PATCH 07/12] pretty cool now

---
 doc/telescope.txt        | 54 +++++++++++++++++++++++++++++-----------
 lua/telescope/config.lua | 20 ++++++++++++---
 lua/telescope/init.lua   |  8 +++---
 3 files changed, 59 insertions(+), 23 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 2fa78e8d2c..7f8dbc9e61 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -8,33 +8,57 @@ To find out more:
 https://github.com/nvim-telescope/telescope.nvim
 
 telescope.extensions()                                *telescope.extensions()*
-        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.
+    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.load_extension({name})                  *telescope.load_extension()*
-        Load an extension.
+    Load an extension.
 
-        Parameters: ~
-            {name} (string)  Name of the extension
+    Parameters: ~
+        {name} (string)  Name of the extension
 
 
 telescope.register_extension({mod})           *telescope.register_extension()*
-        Register an extension. To be used by plugin authors.
+    Register an extension. To be used by plugin authors.
 
-        Parameters: ~
-            {mod} (table)  Module
+    Parameters: ~
+        {mod} (table)  Module
 
 
 telescope.setup({opts})                                    *telescope.setup()*
-        Setup function to be run by user. Configures the defaults, extensions
+    Setup function to be run by user. Configures the defaults, extensions
+     and other aspects of telescope.
 
-        and other aspects of telescope.
 
-        Parameters: ~
-            {opts} (table)  Configuration opts. Keys: defaults, extensions
+    Valid keys for {opts.defaults}
+
+    scroll_strategy: ~
+        Determines what happens you try to scroll past view of the picker.
+
+          Available options are:
+          - "cycle" (default)
+          - "limit"
+
+    selection_strategy: ~
+        Determines how the cursor acts after each sort iteration.
+
+          Available options are:
+          - "reset" (default)
+          - "follow"
+          - "row"
+
+    sorting_strategy: ~
+        Determines the direction "better" results are sorted towards.
+
+          Available options are:
+          - "descending" (default)
+          - "ascending"
+
+    Parameters: ~
+        {opts} (table)  Configuration opts. Keys: defaults, extensions
 
 
 
@@ -53,7 +77,7 @@ This will use the default configuration options.
   Other configuration options are still in flux at the moment
 
 builtin.live_grep()                                      *builtin.live_grep()*
-        Live grep means grep as you type.
+    Live grep means grep as you type.
 
 
 
diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index ac2693eaca..9b749edabf 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -30,6 +30,7 @@ function config.set_defaults(defaults)
   end
 
   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)
@@ -39,18 +40,29 @@ function config.set_defaults(defaults)
   end
 
   set("sorting_strategy", "descending", [[
-    Sorting strategy determines the direction "better" results are sorted towards.
+    Determines the direction "better" results are sorted towards.
 
       Available options are:
-      - "descending"
+      - "descending" (default)
       - "ascending"
   ]])
 
   set("selection_strategy", "reset", [[
-    nevermind, read the source code.
+    Determines how the cursor acts after each sort iteration.
+
+      Available options are:
+      - "reset" (default)
+      - "follow"
+      - "row"
   ]])
 
-  set("scroll_strategy", "cycle")
+  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 2aa95195cc..5d4f731eeb 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -56,20 +56,20 @@ telescope.extensions = require('telescope._extensions').manager
 telescope.__format_setup_keys = function()
   -- return 'Valid keys:\n' .. vim.inspect(vim.tbl_keys(require('telescope.config').values)) 
 
-  local result = "Valid Setup Keys:\n"
 
   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]
 
     -- hint: make sure you're considering UNICODE?!?!?!?
-    result = result .. "\n"
-      .. string.format("\n%s:\n", name)
-      .. string.format("    %s\n", desc)
+    table.insert(result, "")
+    table.insert(result, string.format("%s: ~", name))
+    table.insert(result, string.format("    %s", desc))
   end
 
   return result

From 82a2f831c9b54b46ccda6adc9361a4c0ffab75bb Mon Sep 17 00:00:00 2001
From: Github Actions <actions@github>
Date: Wed, 24 Feb 2021 21:11:40 +0000
Subject: [PATCH 08/12] [Actions] Generate Documentation skip-checks: true

---
 doc/telescope.txt | 25 -------------------------
 1 file changed, 25 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 7f8dbc9e61..81e66aa311 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -32,31 +32,6 @@ telescope.setup({opts})                                    *telescope.setup()*
     Setup function to be run by user. Configures the defaults, extensions
      and other aspects of telescope.
 
-
-    Valid keys for {opts.defaults}
-
-    scroll_strategy: ~
-        Determines what happens you try to scroll past view of the picker.
-
-          Available options are:
-          - "cycle" (default)
-          - "limit"
-
-    selection_strategy: ~
-        Determines how the cursor acts after each sort iteration.
-
-          Available options are:
-          - "reset" (default)
-          - "follow"
-          - "row"
-
-    sorting_strategy: ~
-        Determines the direction "better" results are sorted towards.
-
-          Available options are:
-          - "descending" (default)
-          - "ascending"
-
     Parameters: ~
         {opts} (table)  Configuration opts. Keys: defaults, extensions
 

From 48c35f97e53c4f9e99b5186742df2e7c9f2f6a23 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 24 Feb 2021 16:15:50 -0500
Subject: [PATCH 09/12] make sure telescope is loaded first

---
 scripts/gendocs.lua | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index ee4db02ad5..7be0d4ffd0 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -1,3 +1,6 @@
+-- Setup telescope with defaults
+require('telescope').setup()
+
 local docgen = require('docgen')
 
 local docs = {}

From 3946a814c7ebad1948abeee8a4951b82a00a38f1 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 24 Feb 2021 16:18:22 -0500
Subject: [PATCH 10/12] Add updates. Maybe this will not delete now?

---
 doc/telescope.txt              | 25 +++++++++++++++++++++++++
 lua/telescope/builtin/init.lua |  8 ++++----
 lua/telescope/init.lua         |  4 ----
 3 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 81e66aa311..7f8dbc9e61 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -32,6 +32,31 @@ telescope.setup({opts})                                    *telescope.setup()*
     Setup function to be run by user. Configures the defaults, extensions
      and other aspects of telescope.
 
+
+    Valid keys for {opts.defaults}
+
+    scroll_strategy: ~
+        Determines what happens you try to scroll past view of the picker.
+
+          Available options are:
+          - "cycle" (default)
+          - "limit"
+
+    selection_strategy: ~
+        Determines how the cursor acts after each sort iteration.
+
+          Available options are:
+          - "reset" (default)
+          - "follow"
+          - "row"
+
+    sorting_strategy: ~
+        Determines the direction "better" results are sorted towards.
+
+          Available options are:
+          - "descending" (default)
+          - "ascending"
+
     Parameters: ~
         {opts} (table)  Configuration opts. Keys: defaults, extensions
 
diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua
index 986356c6ef..a625ac1823 100644
--- a/lua/telescope/builtin/init.lua
+++ b/lua/telescope/builtin/init.lua
@@ -2,13 +2,13 @@
 
 ---@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 ]]
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 5d4f731eeb..80cb986c27 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -54,9 +54,6 @@ end
 telescope.extensions = require('telescope._extensions').manager
 
 telescope.__format_setup_keys = function()
-  -- return 'Valid keys:\n' .. vim.inspect(vim.tbl_keys(require('telescope.config').values)) 
-
-
   local descriptions = require('telescope.config').descriptions
 
   local names = vim.tbl_keys(descriptions)
@@ -66,7 +63,6 @@ telescope.__format_setup_keys = function()
   for _, name in ipairs(names) do
     local desc = descriptions[name]
 
-    -- hint: make sure you're considering UNICODE?!?!?!?
     table.insert(result, "")
     table.insert(result, string.format("%s: ~", name))
     table.insert(result, string.format("    %s", desc))

From 1620e412fc54c294cbe5f54613fed092d876c631 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 24 Feb 2021 16:22:34 -0500
Subject: [PATCH 11/12] Add defaults tags as well

---
 doc/telescope.txt      | 3 +++
 lua/telescope/init.lua | 1 +
 2 files changed, 4 insertions(+)

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 7f8dbc9e61..14d0f6f375 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -35,6 +35,7 @@ telescope.setup({opts})                                    *telescope.setup()*
 
     Valid keys for {opts.defaults}
 
+                                       *telescope.defaults.scroll_strategy*
     scroll_strategy: ~
         Determines what happens you try to scroll past view of the picker.
 
@@ -42,6 +43,7 @@ telescope.setup({opts})                                    *telescope.setup()*
           - "cycle" (default)
           - "limit"
 
+                                    *telescope.defaults.selection_strategy*
     selection_strategy: ~
         Determines how the cursor acts after each sort iteration.
 
@@ -50,6 +52,7 @@ telescope.setup({opts})                                    *telescope.setup()*
           - "follow"
           - "row"
 
+                                      *telescope.defaults.sorting_strategy*
     sorting_strategy: ~
         Determines the direction "better" results are sorted towards.
 
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 80cb986c27..9530f65efb 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -64,6 +64,7 @@ telescope.__format_setup_keys = function()
     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

From 4154bca1f92c2e0c25980f2d4e021132d45bb6a7 Mon Sep 17 00:00:00 2001
From: TJ DeVries <devries.timothyj@gmail.com>
Date: Wed, 24 Feb 2021 17:02:31 -0500
Subject: [PATCH 12/12] :smile:

---
 doc/secret.txt                              |  32 +++++
 doc/telescope.txt                           | 116 +++++++++++++++-
 lua/telescope/init.lua                      |   2 +
 lua/telescope/pickers/layout_strategies.lua | 142 +++++++++++---------
 scripts/gendocs.lua                         |   4 +-
 5 files changed, 226 insertions(+), 70 deletions(-)
 create mode 100644 doc/secret.txt

diff --git a/doc/secret.txt b/doc/secret.txt
new file mode 100644
index 0000000000..e872ca45aa
--- /dev/null
+++ b/doc/secret.txt
@@ -0,0 +1,32 @@
+================================================================================
+                                                      *telescope.theprimeagen*
+
+To The Viewers: ~
+
+Oh why hello, I didn't see you there. So nice of you to join us. The Primeagen
+must have sent you here.
+
+The places you want to look for help are: (you can do `:help <name>` below)
+    - |telescope.nvim|
+    - |telescope.setup|
+    - |telescope.builtin|
+    - |telescope.layout|
+    - |telescope.actions|
+
+I hope you enjoy telescope & Neovim. May your programming always be fun and
+your vimming be quick.
+
+
+
+To The Primeagen: ~
+
+Cyrnfr ernq guvf uryc znahny orsber pnyyvat zr ng 3 NZ jvgu gryrfpbcr
+rzretrapvrf. V xabj ynfg gvzr jr fnirq gur ragver fgernzvat vaqhfgel, ohg
+V unir n lbhat fba jub xrrcf zr hc ng avtug nyy ol uvzfrys. OGJ, unir lbh
+pbafvqrerq fraqvat culfvpny QIQf sbe znkvzhz dhnyvgl naq rneyl npprff gb arj
+pbagrag? Vg frrzf yvxr vg pbhyq or n cerggl pbby vqrn.
+
+#FunzryrffFrysCebzbgvba: uggcf://tvguho.pbz/fcbafbef/gwqrievrf
+
+
+ vim:tw=78:ts=8:ft=help:norl:
diff --git a/doc/telescope.txt b/doc/telescope.txt
index 14d0f6f375..d37db92085 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -8,29 +8,37 @@ To find out more:
 https://github.com/nvim-telescope/telescope.nvim
 
 telescope.extensions()                                *telescope.extensions()*
+
     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.
+    While the docs currently generate this as a function, it's actually a table.
+    Sorry.
+
 
 
 telescope.load_extension({name})                  *telescope.load_extension()*
+
     Load an extension.
 
+
     Parameters: ~
         {name} (string)  Name of the extension
 
 
 telescope.register_extension({mod})           *telescope.register_extension()*
+
     Register an extension. To be used by plugin authors.
 
+
     Parameters: ~
         {mod} (table)  Module
 
 
 telescope.setup({opts})                                    *telescope.setup()*
+
     Setup function to be run by user. Configures the defaults, extensions
-     and other aspects of telescope.
+    and other aspects of telescope.
+
 
 
     Valid keys for {opts.defaults}
@@ -80,8 +88,110 @@ This will use the default configuration options.
   Other configuration options are still in flux at the moment
 
 builtin.live_grep()                                      *builtin.live_grep()*
+
     Live grep means grep as you type.
 
 
 
+
+================================================================================
+                                                              *telescope.layout*
+
+
+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|
+
+
+layout_strategies.center()                        *layout_strategies.center()*
+
+    Centered layout wih smaller default sizes (I think)
+
+       +--------------+
+       |    Preview   |
+       +--------------+
+       |    Prompt    |
+       +--------------+
+       |    Result    |
+       |    Result    |
+       |    Result    |
+       +--------------+
+
+
+
+
+layout_strategies.flex()                            *layout_strategies.flex()*
+
+    Swap between `horizontal` and `vertical` strategies based on the window
+    width
+      -  Supports `vertical` or `horizontal` features
+
+      Uses:
+       flip_columns
+       flip_lines
+
+
+
+layout_strategies.horizontal()                *layout_strategies.horizontal()*
+
+    Horizontal previewer
+
+      +-------------+--------------+
+      |             |              |
+      |   Results   |              |
+      |             |    Preview   |
+      |             |              |
+      +-------------|              |
+      |   Prompt    |              |
+      +-------------+--------------+
+
+
+
+layout_strategies.vertical()                    *layout_strategies.vertical()*
+
+    Vertical perviewer stacks the items on top of each other.
+
+       +-----------------+
+       |    Previewer    |
+       |    Previewer    |
+       |    Previewer    |
+       +-----------------+
+       |     Result      |
+       |     Result      |
+       |     Result      |
+       +-----------------+
+       |     Prompt      |
+       +-----------------+
+
+
+
+
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 9530f65efb..2269efe5cd 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -14,10 +14,12 @@ local telescope = {}
 ---
 --- 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
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index 334ac2f55b..382d9a65d1 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 {}
 
diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua
index 7be0d4ffd0..0cf8a80014 100644
--- a/scripts/gendocs.lua
+++ b/scripts/gendocs.lua
@@ -5,14 +5,12 @@ local docgen = require('docgen')
 
 local docs = {}
 
---- Wowow
----@param hello number|table: hello?
----@eval {["hello"] = 5}
 docs.test = function()
   -- TODO: Fix the other files so that we can add them here.
   local input_files = {
     "./lua/telescope/init.lua",
     "./lua/telescope/builtin/init.lua",
+    "./lua/telescope/pickers/layout_strategies.lua",
   }
 
   table.sort(input_files, function(a, b)