From cd130cf9ae8fa3a47f3fc080735c1e65e6e19ea3 Mon Sep 17 00:00:00 2001
From: Fangrui Song <i@maskray.me>
Date: Sat, 31 Mar 2018 17:59:52 -0700
Subject: [PATCH] Created Initialization options (markdown)

---
 Initialization-options.md | 52 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 Initialization-options.md

diff --git a/Initialization-options.md b/Initialization-options.md
new file mode 100644
index 0000000..7b9a4be
--- /dev/null
+++ b/Initialization-options.md
@@ -0,0 +1,52 @@
+You need to configure your language client plugin to send initialization options to the ccls process (the language server). `cacheDirectory` points to a directory (relative or absolute) storing indexing files so that next time ccls can load these indexing results without full indexing.
+```json
+{
+  "initializationOptions": {
+    "cacheDirectory": "/tmp/ccls",
+  }
+}
+```
+
+You can also pass options through the command line option `--init`:
+
+* shell: `--init='{"enableComments": 2}'` . Single quotes are used to escape words in shell.
+* Emacs: `(setq ccls-extra-init-params '(:enableComments 2 :cacheFormat "msgpack"))`
+
+## `indexerCount` number of indexer threads
+
+If `indexerCount` is 0, use 80% of `std::thread::hardware_concurrency()`.
+
+## `index.comments`: indexing comments
+
+- `0`, don't index comments
+- `1`, index Doxygen comment markers
+- `2`, default, use `-fparse-all-comments` and recognize plain `//` `/* */` besides Doxygen comment markers
+
+With the value larger than 0, cquery will index comments associated with functions/types/variables (macros are not handled due to `clang_Cursor_getRawCommentText`'s peculiarity).
+
+This feature requires UI support as multi-line hover results poses a problem to editors:
+
+* Emacs
+  + lsp-ui-doc https://github.com/emacs-lsp/lsp-ui
+  + lsp-mode eldoc  See https://github.com/emacs-lsp/lsp-mode/pull/224
+* Vim
+  + LanguageClient-neovim: preview window
+
+## `cacheFormat`: serialization format of cache files
+
+Two cache serialization formats are supported.
+
+```json
+"cacheFormat": "json"
+"cacheFormat": "msgpack"
+```
+
+`"json"` generates `cacheDirectory/.../xxx.json` files which can be pretty printed with jq.
+
+`"msgpack"` uses a compact binary serialization format (the underlying wire format is [MessagePack](https://msgpack.org/index.html)) which typically takes only 60% of the corresponding JSON size, but is difficult to inspect. `"msgpack"` does not store map keys and you need to re-index whenever a struct member has changed.
+
+## `completion.filterAndSort`: completion filtering and sorting
+
+ccls filters and sorts completions to try to be nicer to clients that can't handle big numbers of completion candidates. This behaviour can be disabled by specifying `false` for the option.
+
+This option is the most useful for LSP clients that implement their own filtering and sorting logic.
\ No newline at end of file