[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 ↗

(On Diff #217834)

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 ↗

(On Diff #217834)

instead of enables let's say improves ?

361 ↗

(On Diff #217834)

drop the global

362 ↗

(On Diff #217834)

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

363 ↗

(On Diff #217834)

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?

364 ↗

(On Diff #217834)

s/canb/can
s/disable/disabled

365 ↗

(On Diff #217834)

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.

369 ↗

(On Diff #217834)

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

363 ↗

(On Diff #217834)

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

363 ↗

(On Diff #217834)

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

365 ↗

(On Diff #217834)

seems to be the same?

[hokein]

address comments.

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

365 ↗

(On Diff #217834)

oops, I forgot this comment.

[kadircet]

thanks, lgtm!

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

364 ↗

(On Diff #221523)

s/shareds/shards

[hokein]

Fix a typo.

clang-tools-extra/trunk/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.*