From 36746ec679207004ed95e09c9ca212a3e14cf920 Mon Sep 17 00:00:00 2001
From: Fangrui Song <i@maskray.me>
Date: Sun, 23 Sep 2018 11:00:26 -0700
Subject: [PATCH] diagnostics

---
 Initialization-options.md | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/Initialization-options.md b/Initialization-options.md
index f3abcd0..d23b23b 100644
--- a/Initialization-options.md
+++ b/Initialization-options.md
@@ -1,6 +1,7 @@
 You need to configure your language client plugin to send initialization options to the ccls process (the language server).
 
-Each language client has its own way to specify initialization options. ccls supports a command line option `--init`:
+Each language client has its own way to specify initialization options.
+ccls (server-side) supports the command line option `--init` to override client-side initialization options:
 
 * zsh: `--init='{"index": {"comments": 2}}'`
 
@@ -28,24 +29,26 @@ If cache files were built with project root `/tmp/container`, and you want to re
 
 Copy cache files:
 ```zsh
-rsync -a /tmp/ccls/@tmp@container@/ /tmp/ccls/@tmp@host@/ # files under project root
+rsync -a /tmp/ccls/@tmp@container/ /tmp/ccls/@tmp@host/ # files under project root
 rsync -a /tmp/ccls/@@tmp@container/ /tmp/ccls/@@tmp@host/ # files outside of project root
 ```
 
-Open `/tmp/host/a.cc`, the cache file `/tmp/ccls/@tmp@host/a.cc.blob` will be reused. When a.cc is saved (re-indexed), the newly generated a.cc.blob will not contain /tmp/container paths any more.
+Open `/tmp/host/a.cc`, the cache file `/tmp/ccls/@tmp@host/a.cc.blob` will be reused. When `a.cc` is saved (re-indexed), the newly generated `a.cc.blob` will not contain `/tmp/container` paths any more.
 
-## `diagnostics.onOpen: true` `diagnostics.onChange: true` `diagnostics.onSave: false`
+## `diagnostics.onOpen: 0` `diagnostics.onChange: 1000` `diagnostics.onSave: 0`
 
-By default, diagnostics are emitted when opening a document or a change is made.
-Diagnostics require parsing the document. If it is slow for you, consider:
+Time to wait before computing diagnostics for `textDocument/{didOpen,didChange,didSave}`.
+
+By default:
+
+* `diagnostics.onOpen: 0`: diagnostics are emitted immediately when a document is opened.
+* `diagnostics.onChange: 1000`: after receiving a `textDocument/didChange`, wait up to 1000ms (1s). Changes in this period of time only lead to one computation.
+* `diagnostics.onSave: 0`: diagnostics are emitted immediately when a document is save.
+
+Diagnostics require parsing the document.  If `diagnostics.onChange: 1000` makes you feel slow, consider:
 
 ```javascript
-{
-  "diagnostics": {
-    "onChange": false,
-    "onSave": true
-  }
-}
+{ "diagnostics": { "onChange": -1, } }
 ```
 
 ## `index.threads`: number of indexer threads
@@ -89,13 +92,12 @@ You usually want to use `index.multiVersionBlacklist` to exclude system headers.
 
 ## `index.onChange`: re-index for every change
 
-Default: `false`, re-index when a document is saved.
+Default: `false`
 
-Set it to `true` to re-index for every change to a document.
+A document is re-indexed when saved, updating the global index incrementally.
+If set to `true`, a document is re-indexed for every (unsaved) change. The performance may suffer, but probably convenient for playground projects.
 
-The performance may suffer a lot.
-
-This is best used in conjunction with empty empty `cacheDirectory` to avoid writing cache files:
+This is best used in conjunction with empty `cacheDirectory` to avoid writing cache files to disk:
 ```javascript
 {
   "cacheDirectory": "",