docs: expand clangd instructions

Add some additional information about running clangd for LSP when clang
is not your normal compiler.

Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-By: Tim Small <tim@seoss.co.uk>

diff --git a/docs/clangd.rst b/docs/clangd.rst
index 93570ae17884e5e05d8333ae496efd884f83141d..25529948f6d82b744c2b2b4266faefe396ba67bd 100644 (file)
--- a/docs/clangd.rst
+++ b/docs/clangd.rst
@@ -40,6 +40,14 @@ Create a separate build directory with a ``clangd`` compatible
 
    CC=clang CXX=clang++ meson setup build-clang
 
+There are a small number of source files that are generated as part of the
+build process. In order to navigate this generated source code, you should also
+execute a build in this directory:
+
+::
+
+    ninja -C build-clang
+
 Point ``clangd`` (v12 or later) at the correct
 ``compile_commands.json`` by placing the following into a
 ``.clangd`` file in the root of the project:
@@ -49,3 +57,12 @@ Point ``clangd`` (v12 or later) at the correct
    ---
    CompileFlags:
      CompilationDatabase: "build-clang"
+
+
+Please note that if you are not using clang for your daily development, the
+``build-clang`` directory can get out of sync with the current state of the
+project over time. When you update your git checkout, new files may be added or
+configuration options changed and ``clangd`` may start to behave unpredictably.
+In this case, you will need to update your compilation database by doing a new
+build in the ``build-clang`` directory. This should allow clangd to work
+reliably again.