[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

358–360

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.

360

instead of enables let's say improves ?

361

drop the global

361–362

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

362–367

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?

363

s/canb/can
s/disable/disabled

364

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.

370

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 ?

[hokein]

Address comments.

[hokein]

fix a typo

[hokein]

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

362–367

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

362–367

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

364

seems to be the same?

[hokein]

address comments.

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

364

oops, I forgot this comment.

[kadircet]

thanks, lgtm!

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

364

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.
+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.
+
+- the index is saved to the ``.clangd/index`` in the project root;
+- clangd only uses idle cores to build the index, you can limit the total
+  amount of cores by passing the `-j=<number>` flag;
+- background indexing can be disabled by the ``--background-index=false`` flag;
+  if it is disabled, clangd doesn't have a global view of the whole project, it
+  only has a view on symbols coming from files you are currently editing;
 
-- Generate an index file using `clangd-indexer
+Build Index Manually
+====================
+
+**DISCLAMER: 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>`__
-  Then you can pass generated index file to clangd using
-  `-index-file=/path/to/index_file`.  *Note that clangd-indexer isn't
+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.*