Elaborate the comment, include flag in docs

Author: mrkajetanp

llvm/CMakeLists.txt

@@ -289,7 +289,9 @@ if(LLVM_CCACHE_BUILD)
     set(LLVM_CCACHE_PARAMS "CCACHE_CPP2=yes CCACHE_HASHDIR=yes CCACHE_SLOPPINESS=pch_defines,time_macros"
         CACHE STRING "Parameters to pass through to ccache")
 
-    # Using precompiled headers with ccache builds can result in intermittent CI failures
+    # FIXME: This is a workaround for an unknown underlying issue where the header file
+    # changes but then the pch does not get rebuilt before its dependencies.
+    # See: https://github.com/llvm/llvm-project/issues/142449
     set(LLVM_CCACHE_PCH OFF CACHE BOOL "Use precompiled headers in ccache builds")
     if (NOT LLVM_CCACHE_PCH)
       set(CMAKE_DISABLE_PRECOMPILE_HEADERS "ON")

llvm/docs/CMake.rst

@@ -412,7 +412,9 @@ enabled sub-projects. Nearly all of these variable names begin with
   Defaults to OFF.  The size and location of the cache maintained
   by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
   options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
-  variables, respectively.
+  variables, respectively. By default, enabling the ccache build will disable
+  using precompiled headers as they have been known to cause intermittent CI
+  failures. This can be adjusted via the LLVM_CCACHE_PCH option.
 
 **LLVM_CODE_COVERAGE_TARGETS**:STRING
   If set to a semicolon separated list of targets, those targets will be used