feat(docs): autogenerate default_config docs

Problem:
Docs are manually maintained everywhere for no good reason.

Solution:
- revert commit 9dc02492c4a457479f8a0ec7a65aac1852ff59c0
- provide a "gF" friendly link to the source

15 files changed, 56 insertions, 92 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 979ff78b..212788a0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,9 +29,11 @@ To add a new language server, start with a minimal skeleton. See `:help lspconfi
 
 When choosing a config name, convert dashes (`-`) to underscores (`_`). If the name of the server is a unique name (`pyright`, `clangd`) or a commonly used abbreviation (`zls`), prefer this as the server name. If the server instead follows the pattern x-language-server, prefer the convention `x_ls` (`jsonnet_ls`). 
 
-Populate the `config` table with a `default_config` and `docs` table.
+Populate the `config` table with `default_config` and `docs` tables. Avoid over-architected code. Put lists directly in
+the `default_config` don't add indirection by defining variables elsewhere in the module. The docs are auto-generated by
+reading your `config` source code, so the less indirection in your code, the more useful and obvious the docs will be.
 
-`default_config` should include at minimum:
+`default_config` should include:
 
 * `cmd`: a list which includes the executable name as the first entry, with arguments constituting subsequent list elements (`--stdio` is common).
   ```lua
diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt
index 553d7362..4fb5fd19 100644
--- a/doc/lspconfig.txt
+++ b/doc/lspconfig.txt
@@ -179,18 +179,18 @@ The `configs` module is a singleton where configs are defined. The
 `vim.validate` schema is: >
 
     configs.SERVER_NAME = {
-      default_config = {'t'},
-      on_new_config = {'f', true},
-      on_attach = {'f', true},
-      commands = {'t', true},
-      docs = {'t', true},
+      default_config = {'table'},
+      on_new_config = {'function', true},
+      on_attach = {'function', true},
+      commands = {'table', true},
+      docs = {'table', true},
     }
 <
 where the structure of `docs` is: >
 
     docs = {
-      description = {'s', true},
-      default_config = {'t', true},
+      description = {'string', true},
+      default_config = {'table', true},
     }
 <
 `commands` is a map of `name:definition` key:value pairs, where `definition`
diff --git a/lua/lspconfig/configs/ada_ls.lua b/lua/lspconfig/configs/ada_ls.lua
index 3a8c79b0..c532f641 100644
--- a/lua/lspconfig/configs/ada_ls.lua
+++ b/lua/lspconfig/configs/ada_ls.lua
@@ -25,8 +25,5 @@ require('lspconfig').ada_ls.setup{
 }
 ```
 ]],
-    default_config = {
-      root_dir = [[util.root_pattern("Makefile", ".git", "*.gpr", "*.adc")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/aiken.lua b/lua/lspconfig/configs/aiken.lua
index 8025fe1e..3c9e2562 100644
--- a/lua/lspconfig/configs/aiken.lua
+++ b/lua/lspconfig/configs/aiken.lua
@@ -17,9 +17,5 @@ A language server for Aiken Programming Language.
 
 It can be i
 ]],
-    default_config = {
-      cmd = { 'aiken', 'lsp' },
-      root_dir = [[root_pattern("aiken.toml", ".git")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/clangd.lua b/lua/lspconfig/configs/clangd.lua
index f5fc804d..ffee2af7 100644
--- a/lua/lspconfig/configs/clangd.lua
+++ b/lua/lspconfig/configs/clangd.lua
@@ -46,33 +46,29 @@ local function symbol_info()
   end, bufnr)
 end
 
-local root_files = {
-  '.clangd',
-  '.clang-tidy',
-  '.clang-format',
-  'compile_commands.json',
-  'compile_flags.txt',
-  'configure.ac', -- AutoTools
-}
-
-local default_capabilities = {
-  textDocument = {
-    completion = {
-      editsNearCursor = true,
-    },
-  },
-  offsetEncoding = { 'utf-8', 'utf-16' },
-}
-
 return {
   default_config = {
     cmd = { 'clangd' },
     filetypes = { 'c', 'cpp', 'objc', 'objcpp', 'cuda', 'proto' },
     root_dir = function(fname)
-      return util.root_pattern(unpack(root_files))(fname) or util.find_git_ancestor(fname)
+      return util.root_pattern(
+        '.clangd',
+        '.clang-tidy',
+        '.clang-format',
+        'compile_commands.json',
+        'compile_flags.txt',
+        'configure.ac' -- AutoTools
+      )(fname) or util.find_git_ancestor(fname)
     end,
     single_file_support = true,
-    capabilities = default_capabilities,
+    capabilities = {
+      textDocument = {
+        completion = {
+          editsNearCursor = true,
+        },
+      },
+      offsetEncoding = { 'utf-8', 'utf-16' },
+    }
   },
   commands = {
     ClangdSwitchSourceHeader = {
@@ -101,19 +97,5 @@ https://clangd.llvm.org/installation.html
 - clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
   specified as compile_commands.json, see https://clangd.llvm.org/installation#compile_commandsjson
 ]],
-    default_config = {
-      root_dir = [[
-        root_pattern(
-          '.clangd',
-          '.clang-tidy',
-          '.clang-format',
-          'compile_commands.json',
-          'compile_flags.txt',
-          'configure.ac',
-          '.git'
-        )
-      ]],
-      capabilities = [[default capabilities, with offsetEncoding utf-8]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/ts_ls.lua b/lua/lspconfig/configs/ts_ls.lua
index 38a7c800..1eafd91b 100644
--- a/lua/lspconfig/configs/ts_ls.lua
+++ b/lua/lspconfig/configs/ts_ls.lua
@@ -83,8 +83,5 @@ require'lspconfig'.ts_ls.setup{
 
 `filetypes` is extended here to include Vue SFC.
 ]],
-    default_config = {
-      root_dir = [[root_pattern("tsconfig.json", "jsconfig.json", "package.json", ".git")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/ttags.lua b/lua/lspconfig/configs/ttags.lua
index d57a7967..bbc762d5 100644
--- a/lua/lspconfig/configs/ttags.lua
+++ b/lua/lspconfig/configs/ttags.lua
@@ -10,8 +10,5 @@ return {
     description = [[
 https://github.com/npezza93/ttags
     ]],
-    default_config = {
-      root_dir = [[root_pattern(".git")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/typeprof.lua b/lua/lspconfig/configs/typeprof.lua
index ab9dc8ef..09ef2a2f 100644
--- a/lua/lspconfig/configs/typeprof.lua
+++ b/lua/lspconfig/configs/typeprof.lua
@@ -12,8 +12,5 @@ https://github.com/ruby/typeprof
 
 `typeprof` is the built-in analysis and LSP tool for Ruby 3.1+.
     ]],
-    default_config = {
-      root_dir = [[root_pattern("Gemfile", ".git")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/uiua.lua b/lua/lspconfig/configs/uiua.lua
index b102f8c3..54d23ac9 100644
--- a/lua/lspconfig/configs/uiua.lua
+++ b/lua/lspconfig/configs/uiua.lua
@@ -16,16 +16,5 @@ The builtin language server of the Uiua interpreter.
 
 The Uiua interpreter can be installed with `cargo install uiua`
 ]],
-    default_config = {
-      cmd = { 'uiua', 'lsp' },
-      filetypes = { 'uiua' },
-      root_dir = [[
-        root_pattern(
-          'main.ua',
-          'fmt.ua',
-          '.git'
-        )
-      ]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/wgsl_analyzer.lua b/lua/lspconfig/configs/wgsl_analyzer.lua
index 2325cc6e..bfa2f5e9 100644
--- a/lua/lspconfig/configs/wgsl_analyzer.lua
+++ b/lua/lspconfig/configs/wgsl_analyzer.lua
@@ -16,8 +16,5 @@ https://github.com/wgsl-analyzer/wgsl-analyzer
 cargo install --git https://github.com/wgsl-analyzer/wgsl-analyzer wgsl_analyzer
 ```
 ]],
-    default_config = {
-      root_dir = [[root_pattern(".git")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/yang_lsp.lua b/lua/lspconfig/configs/yang_lsp.lua
index d4c9b8b6..13f6fa35 100644
--- a/lua/lspconfig/configs/yang_lsp.lua
+++ b/lua/lspconfig/configs/yang_lsp.lua
@@ -12,8 +12,5 @@ https://github.com/TypeFox/yang-lsp
 
 A Language Server for the YANG data modeling language.
 ]],
-    default_config = {
-      root_dir = [[util.find_git_ancestor]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/ziggy_schema.lua b/lua/lspconfig/configs/ziggy_schema.lua
index 2bd01cc8..cd19cf35 100644
--- a/lua/lspconfig/configs/ziggy_schema.lua
+++ b/lua/lspconfig/configs/ziggy_schema.lua
@@ -14,8 +14,5 @@ https://ziggy-lang.io/documentation/ziggy-lsp/
 Language server for schema files of the Ziggy data serialization format
 
 ]],
-    default_config = {
-      root_dir = [[util.find_git_ancestor]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/zk.lua b/lua/lspconfig/configs/zk.lua
index 57a1ea1a..b24f1686 100644
--- a/lua/lspconfig/configs/zk.lua
+++ b/lua/lspconfig/configs/zk.lua
@@ -72,8 +72,5 @@ https://github.com/mickael-menu/zk
 
 A plain text note-taking assistant
 ]],
-    default_config = {
-      root_dir = [[root_pattern(".zk")]],
-    },
   },
 }
diff --git a/lua/lspconfig/configs/zls.lua b/lua/lspconfig/configs/zls.lua
index 8deeda97..540f4bd8 100644
--- a/lua/lspconfig/configs/zls.lua
+++ b/lua/lspconfig/configs/zls.lua
@@ -18,9 +18,5 @@ https://github.com/zigtools/zls
 
 Zig LSP implementation + Zig Language Server
         ]],
-    default_config = {
-      cmd = { 'zls' },
-      root_dir = [[util.root_pattern("zls.json", "build.zig", ".git")]],
-    },
   },
 }
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index 719e711c..4a62562d 100644
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -9,6 +9,11 @@ local function template(s, params)
   return (s:gsub('{{([^{}]+)}}', params))
 end
 
+--- "@/.../nvim-lspconfig/lua/lspconfig/util.lua" => "./util.lua"
+local function relpath(p)
+  return p:gsub([=[.*[/\\]lua[/\\]lspconfig[/\\]]=], '')
+end
+
 local function map_list(t, func)
   local res = {}
   for i, v in ipairs(t) do
@@ -140,11 +145,29 @@ local function make_lsp_sections()
           end
           return make_section(0, '\n', {
             map_sorted(template_def.default_config, function(k, v)
-              local description = ((docs or {}).default_config or {})[k]
-              if description and type(description) ~= 'string' then
-                description = inspect(description)
-              elseif not description and type(v) == 'function' then
-                description = 'see source file'
+              local description = template_def.default_config[k]
+              if type(v) ~= 'function' then
+                description = inspect(v)
+              else
+                local info = debug.getinfo(v)
+                local relname = relpath(info.source)
+                local file = assert(io.open(string.sub(info.source, 2), 'r'))
+
+                local fnbody = ''
+                local linenr = 0
+                for line in file:lines() do
+                  linenr = linenr + 1
+                  if linenr >= info.linedefined and linenr <= info.lastlinedefined then
+                    fnbody = ('%s\n%s'):format(fnbody, line)
+                  end
+                end
+                io.close(file)
+
+                description = ('-- Source (use "gF" to visit): %s:%d\n'):format(
+                  relname,
+                  info.linedefined,
+                  string.gsub(fnbody, '.*function', 'function')
+                )
               end
               return string.format('- `%s` : \n```lua\n%s\n```', k, description or inspect(v))
             end),
@@ -245,7 +268,7 @@ local function make_lsp_sections()
         if #preamble_parts > 0 then
           table.insert(preamble_parts, '')
         end
-        params.preamble = table.concat(preamble_parts, '\n')
+        params.preamble = vim.trim(table.concat(preamble_parts, '\n'))
       end
 
       return template(lsp_section_template, params)