Add contributing docs and clangd config.

6 files changed, 165 insertions, 12 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..ed953344
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,78 @@
+# Requirements
+
+- Neovim :P
+- The docgen requires \*nix systems for now.
+
+# Generating docs
+
+`scripts/docgen.lua` was written with the intention of being sourced (like with `luafile`)
+from `nvim` to run.
+
+It **must** be run from the .git/project root. This could be modified to try to
+find the .git root with one of our `util.*` functions potentially.
+
+So you can either run nvim with cwd at the project root, or run `nvim +"luafile
+scripts/docgen.lua" +q` from the project root.
+
+This generates a suffix for README.md
+
+# skeleton
+
+skeleton has a `__newindex` metamethod which validates and creates
+an object containing `setup()`, which can then be retrieved and modified.
+
+In vim.validate parlance, this is the format to use.
+
+```
+skeleton.SERVER_NAME = {
+	default_config = {'t'};
+	on_new_config = {'f', true};
+	on_attach = {'f', true};
+	commands = {'t', true};
+	docs = {'t', true};
+}
+docs = {
+  description = {'s', true};
+  default_config = {'t', true};
+}
+```
+
+The docs `default_config` is a table whose keys match the other `default_config`,
+and can be used to specify a string in place of using `vim.inspect(value)` to
+generate the documentation. This is useful for functions, whose output would
+be unhelpful otherwise.
+
+`commands` is a table of key/value pairs from `command_name -> {definition}`.
+The format of `{definition}` is a table where the first array value
+is a function which will be called for this command. The other table values
+are either array values which will be formed into flags for the command or
+special keys like `description`.
+
+Example:
+
+```
+  commands = {
+    TexlabBuild = {
+      function()
+        buf_build(0)
+      end;
+	  "-range";
+      description = "Build the current buffer";
+    };
+  };
+```
+
+
+After you create a `skeleton.SERVER_NAME`, you can add functions to it that you
+wish to expose to the user.
+
+Example:
+
+```
+skeleton.texlab.buf_build = buf_build
+```
+
+After you create a skeleton, you have to `require 'common_lsp/SERVER_NAME'` in
+`lua/common_lsp.lua`, and that's it.
+
+Generate docs and you're done.
diff --git a/README.md b/README.md
index 40b8b4c8..5cb155a4 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ things as much as you want in addition to the defaults that this provides.
 There's a lot of language servers in the world, and not enough time.  See
 [`lua/common_lsp/texlab.lua`](https://github.com/norcalli/nvim-common-lsp/blob/master/lua/common_lsp/texlab.lua)
 and
-[`lua/common_lsp/gopls.lua`](https://github.com/norcalli/nvim-common-lsp/blob/master/lua/common_lsp/gopls.lua)
+[`lua/common_lsp/skeleton.lua`](https://github.com/norcalli/nvim-common-lsp/blob/master/lua/common_lsp/skeleton.lua)
 for examples and ask me questions in the [Neovim
 Gitter](https://gitter.im/neovim/neovim) to help me complete configurations for
 *all the LSPs!*
@@ -26,8 +26,11 @@ implemented from [this excellent list compiled by the coc.nvim
 contributors](https://github.com/neoclide/coc.nvim/wiki/Language-servers) or
 [this other excellent list from the emacs lsp-mode
 contributors](https://github.com/emacs-lsp/lsp-mode#supported-languages)
-and create a new file under `lua/common_lsp/SERVER_NAME.lua`. I recommend
-looking at `lua/common_lsp/texlab.lua` for inspiration.
+and create a new file under `lua/common_lsp/SERVER_NAME.lua`.
+- For a simple server which should only ever have one instance for the entire
+neovim lifetime, I recommend copying `lua/common_lsp/texlab.lua`.
+- For servers which should have a different instance for each project root, I
+recommend copying `lua/common_lsp/gopls.lua`.
 
 ## Progress
 
@@ -52,6 +55,15 @@ In progress:
 
 From vim:
 ```vim
+call common_lsp#texlab({})
+call common_lsp#gopls({})
+
+" These are still TODO, but will be done.
+call common_lsp#clangd({})
+call common_lsp#ccls({})
+call common_lsp#tsserver({})
+
+" Or using a dynamic name.
 call common_lsp#setup("texlab", {})
 call common_lsp#setup("gopls", {})
 ```
@@ -78,7 +90,7 @@ common_lsp.gopls.setup {
 }
 
 -- Build the current buffer.
-common_lsp.texlab.buf_build(0)
+require 'common_lsp'.texlab.buf_build(0)
 ```
 
 ```
@@ -153,6 +165,28 @@ common_lsp.SERVER.setup({config})
 
 # LSP Implementations
 
+## clangd
+
+https://clang.llvm.org/extra/clangd/Installation.html
+
+clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) specified
+as compile_commands.json or, for simpler projects, a compile_flags.txt.
+
+
+
+common_lsp.clangd.setup({config})
+common_lsp#setup("clangd", {config})
+
+```
+  Default Values:
+    capabilities = default capabilities, with offsetEncoding utf-8
+    cmd = { "clangd", "--background-index" }
+    filetypes = { "c", "cpp", "objc", "objcpp" }
+    log_level = 2
+    on_init = function to handle changing offsetEncoding
+    root_dir = root_pattern("compile_commands.json", "compile_flags.txt", ".git")
+    settings = {}
+```
 ## texlab
 
 https://texlab.netlify.com/
@@ -199,6 +233,6 @@ common_lsp#setup("gopls", {config})
     cmd = { "gopls" }
     filetypes = { "go" }
     log_level = 2
-    root_dir = vim's starting directory
+    root_dir = root_pattern("go.mod", ".git")
     settings = {}
 ```
diff --git a/autoload/common_lsp.vim b/autoload/common_lsp.vim
index 7be7a689..9d3444d3 100644
--- a/autoload/common_lsp.vim
+++ b/autoload/common_lsp.vim
@@ -2,11 +2,11 @@ function! common_lsp#setup(name, config)
   return luaeval("require'common_lsp'[_A[1]].setup(_A[2])", [a:name, a:config])
 endfunction
 
-function! common_lsp#texlab(config)
-  call common_lsp#setup("texlab", a:config)
-endfunction
+" function! common_lsp#texlab(config)
+"   call common_lsp#setup("texlab", a:config)
+" endfunction
 
-function! common_lsp#gopls(config)
-  call common_lsp#setup("gopls", a:config)
-endfunction
+" function! common_lsp#gopls(config)
+"   call common_lsp#setup("gopls", a:config)
+" endfunction
 
diff --git a/lua/common_lsp.lua b/lua/common_lsp.lua
index eafd5e2c..4dea8e1e 100644
--- a/lua/common_lsp.lua
+++ b/lua/common_lsp.lua
@@ -1,6 +1,7 @@
 local skeleton = require 'common_lsp/skeleton'
 require 'common_lsp/gopls'
 require 'common_lsp/texlab'
+require 'common_lsp/clangd'
 
 local M = {
   util = require 'common_lsp/util';
diff --git a/lua/common_lsp/clangd.lua b/lua/common_lsp/clangd.lua
new file mode 100644
index 00000000..465af674
--- /dev/null
+++ b/lua/common_lsp/clangd.lua
@@ -0,0 +1,40 @@
+local skeleton = require 'common_lsp/skeleton'
+local util = require 'common_lsp/util'
+local lsp = vim.lsp
+
+local default_capabilities = lsp.protocol.make_client_capabilities()
+default_capabilities.offsetEncoding = {"utf-8", "utf-16"}
+
+skeleton.clangd = {
+  default_config = {
+    cmd = {"clangd", "--background-index"};
+    filetypes = {"c", "cpp", "objc", "objcpp"};
+    root_dir = util.root_pattern("compile_commands.json", "compile_flags.txt", ".git");
+    log_level = lsp.protocol.MessageType.Warning;
+    settings = {};
+    capabilities = default_capabilities;
+    on_init = vim.schedule_wrap(function(client, result)
+      if result.offsetEncoding then
+        client.offset_encoding = result.offsetEncoding
+      end
+    end)
+  };
+  -- commands = {};
+  -- on_new_config = function(new_config) end;
+  -- on_attach = function(client, bufnr) end;
+  docs = {
+    description = [[
+https://clang.llvm.org/extra/clangd/Installation.html
+
+clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) specified
+as compile_commands.json or, for simpler projects, a compile_flags.txt.
+]];
+    default_config = {
+      root_dir = [[root_pattern("compile_commands.json", "compile_flags.txt", ".git")]];
+      on_init = [[function to handle changing offsetEncoding]];
+      capabilities = [[default capabilities, with offsetEncoding utf-8]];
+    };
+  };
+}
+-- vim:et ts=2 sw=2
+
diff --git a/lua/common_lsp/gopls.lua b/lua/common_lsp/gopls.lua
index 306c7f2c..e3061d16 100644
--- a/lua/common_lsp/gopls.lua
+++ b/lua/common_lsp/gopls.lua
@@ -19,7 +19,7 @@ https://github.com/golang/tools/tree/master/gopls
 Google's lsp server for golang.
 ]];
     default_config = {
-      root_dir = "vim's starting directory";
+      root_dir = [[root_pattern("go.mod", ".git")]];
     };
   };
 }