[clangd] Fix the stale documentation about background indexing.

[kadircet]

Thanks for updating this! Pinging @sammccall since he is also working on writing some release docs, might be helpful to bring this to your attention.

clang-tools-extra/docs/clangd/Installation.rst

354–355

I don't think it is necessary to mention the version. It could be better to directly start with

Clangd builds an incremental index over files listed in the compilation database.

354–355

that's not necessarily true, we also save at home directory, and I don't think it is relevant for installation. maybe rather drop it?

354–355

let's mention it will only use your idle cores to build an index and total amount of cores it will use can be limited to X by passing -j=X to clangd

355

s/canb/can
s/disable/disabled

355

I don't think it is relevant for installation section again. But let's make the you probably don't need this a seperate line and make it bold or red ?

356

instead of enables let's say improves ?

356

instead of if it's disabled...

Note that, disabling background-index will limit clangd's knowledge about your codebase to
files you are currently editing.

357

drop the global

[hokein]

Address comments.

[hokein]

fix a typo

[hokein]

clang-tools-extra/docs/clangd/Installation.rst

354–355

I think it is important to mention this. For most cases, .clangd/index is in in the project root, right?

[kadircet]

clang-tools-extra/docs/clangd/Installation.rst

354–355

yes, but still if you are planning to mention this please also mention something like: Index shards for common headers like standard library will be stored in $HOME/.clangd/index

356

seems to be the same?

[hokein]

address comments.

clang-tools-extra/docs/clangd/Installation.rst

356

oops, I forgot this comment.

[kadircet]

thanks, lgtm!

clang-tools-extra/docs/clangd/Installation.rst

356

s/shareds/shards

[hokein]

Fix a typo.

clang-tools-extra/docs/clangd/Installation.rst

 
 If all files in a project use the same build flags, you can put those flags,
 one flag per line, in ``compile_flags.txt`` in your source root.
 
 Clangd will assume the compile command is ``clang $FLAGS some_file.cc``.
 
 Creating this file by hand is a reasonable place to start if your project is
 quite simple.
 
-Project-wide Index
-==================
+Background Indexing
+===================
 
-By default clangd only has a view on symbols coming from files you are
-currently editing. You can extend this view to whole project by providing a
-project-wide index to clangd.  There are two ways to do this.
-
-- Pass an experimental `-background-index` command line argument.  With
-  this feature enabled, clangd incrementally builds an index of projects
-  that you work on and uses the just-built index automatically.
-
-- Generate an index file using `clangd-indexer
-  <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
-  Then you can pass generated index file to clangd using
-  `-index-file=/path/to/index_file`.  *Note that clangd-indexer isn't
-  included alongside clangd in the Debian clang-tools package. You will
-  likely have to build it from source to use this option.*
+clangd builds an incremental index of your project (all files listed in the
+compilation database). The index improves code navigation features (go-to-definition,
+find-references) and code completion.
+
+- clangd only uses idle cores to build the index, you can limit the total
+  amount of cores by passing the `-j=<number>` flag;
+- the index is saved to the ``.clangd/index`` in the project root; index shards
+  for common headers e.g. STL will be stored in `$HOME/.clangd/index`;
+- background indexing can be disabled by the ``--background-index=false`` flag;
+  Note that, disabling background-index will limit clangd's knowledge about your
+  codebase to files you are currently editing.
+
+Build Index Manually
+====================
+
+**DISCLAIMER: This is mainly for clangd developers.**
+
+There is a `clangd-indexer <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
+which generates an index file for your project. To use the index, pass the flag
+`-index=file=/path/to/index_file` to clangd. *Note that clangd-indexer isn't
+included alongside clangd in the Debian clang-tools package. You will likely
+have to build it from source to use this option.*