Doc: Improve Clang for QDoc documentation

Break page into sections to improve readability and content navigation.
Remove "debug build" which is actually wrong.
Add example of setting path to llvm-config on Windows.
Fix bad example of setting environment variable.

Task-number: QTBUG-67189
Change-Id: Ib5404533e8cecdef8ac042fc32c4d993e8d770e4
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

1 files changed, 27 insertions, 10 deletions

diff --git a/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
index 0c3d8b092..74d549f16 100644
--- a/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
+++ b/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
@@ -632,20 +632,37 @@
     \previouspage Getting Started with QDoc
     \nextpage Creating QDoc Configuration Files
 
-    QDoc uses libclang when parsing C++ files as well as function signatures in
-    \l {fn-command} {\\fn} commands. libclang is part of
+    QDoc uses Clang when parsing C++ files as well as function signatures in
+    \l {fn-command} {\\fn} commands. Clang is part of
     \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}.
-    If you are going to build QDoc from source, you need to install
+    Therefore, if you are going to build QDoc from source, you need to install
     \l{http://clang.llvm.org}{LLVM 6.0} or greater first. You can find the
     required pre-built binaries
     \l {http://releases.llvm.org/download.html}{here}.
 
-    The build system uses the tool \c llvm-config to discover the location of
-    Clang on your system, and relies on it being in the c\ PATH environment
-    variable. \c llvm-config is commonly installed with Clang and libclang on
-    Linux systems, and also on macOS if LLVM is installed with Brew. The
-    installation binaries provided for Windows do not include \c llvm-config,
-    but requires that you build the debug version of LLVM from source.
+    \section1 Set Clang location automatically
+
+    The Qt build system uses the tool \c llvm-config to discover the location
+    of LLVM on your system, and relies on the path to llvm-config being in
+    the c\ PATH environment variable to do so. \c llvm-config is commonly
+    installed with LLVM and Clang on Linux systems, and also on macOS if
+    LLVM is installed using Brew.
+
+    On Windows, the installation binaries provided by LLVM do not include
+    \c llvm-config. You may still have it on your system, if you have built
+    LLVM yourself from source. If that is the case, and you want to let the
+    build system find Clang automatically, add the path to \c llvm-config
+    to your \c PATH environment variable. For example:
+
+    \badcode
+        C:\> set PATH=%PATH%;C:\[build directory]\bin\Release"
+    \endcode
+
+    Make sure to set the path to your LLVM build directory. The \c llvm-config
+    executable is located in \c {bin\Release} or \c {bin\Debug}, reflecting the
+    build version.
+
+    \section1 Specify Clang location manually
 
     If \c llvm-config is not in your \c PATH environment variable, or not
     installed on your system, you can still build QDoc, by manually setting the
@@ -660,6 +677,6 @@
     On a Windows system with LLVM installed to \c {C:\Program Files\LLVM}:
 
     \badcode
-        C:\> setx LLVM_INSTALL_DIR "C:\Program Files\LLVM"
+        C:\> set LLVM_INSTALL_DIR="C:\Program Files\LLVM"
     \endcode
 */