Doc: Split up "Parsing C++ Files with the Clang Code Model"

Turn "Use compilation databases" into a separate topic.

Task-number: QTCREATORBUG-29361
Change-Id: I022dcd1e0f59293be42b0f953084c63349d5600c
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Reviewed-by: <github-actions-qt-creator@cristianadam.eu>

doc/qtcreator/src/cmake/creator-projects-cmake.qdoc

@@ -37,7 +37,7 @@
     \list
         \li For CMake version 3.5 or later, generate a
             \l{CMake: CMAKE_EXPORT_COMPILE_COMMANDS}{compilation database} and
-            open that in \QC, as described in \l{Using Compilation Databases}.
+            open that in \QC, as described in \l{Use compilation databases}.
         \li Create an ad-hoc project file for a qmake build using
             \c{qmake -project} and \l{Open projects}{open} that in \QC.
             Typically, you cannot compile such projects without manual changes.
@@ -49,7 +49,8 @@
 
     \sa {Build with CMake}{How To: Build with CMake}, {CMake Build Configuration},
     {Configure projects for building}, {Configure projects for running},
-    {Debug CMake project files}, {Deploying to Remote Linux}, {Open projects}
+    {Debug CMake project files}, {Deploying to Remote Linux}, {Open projects},
+    {Use compilation databases}
 */
 
 /*!

doc/qtcreator/src/editors/creator-code-syntax.qdoc

@@ -34,7 +34,7 @@
 
     You can use the icons in the tooltip popup to copy the error or
     warning message to the clipboard, to hide messages of a particular type,
-    or to \l{Configuring clangd}{change the diagnostics settings}. Select
+    or to \l{Clangd}{change the diagnostics settings}. Select
     the \uicontrol {Annotation Settings} link to specify the position
     of the line annotations.
 

doc/qtcreator/src/editors/creator-editors-writing-code.qdoc

@@ -89,13 +89,6 @@
 
             You can use a diff editor to compare two versions of a file and
             view the differences side-by-side in the \uicontrol Edit mode.
-
-        \li \l{Parsing C++ Files with the Clang Code Model}
-
-            The Clang code model offers some of the same services as the
-            built-in C/C++ code model, such as code
-            completion, syntactic and semantic highlighting, diagnostics,
-            tooltips, outline of symbols, and renaming of local symbols.
         \endif
 
     \endlist

doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc

@@ -1,4 +1,4 @@
-// Copyright (C) 2022 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 // **********************************************************************
@@ -8,11 +8,14 @@
 // **********************************************************************
 
 /*!
-    \previouspage creator-diff-editor.html
     \page creator-clang-codemodel.html
-    \nextpage creator-finding-overview.html
+    \previouspage creator-reference.html
 
-    \title Parsing C++ Files with the Clang Code Model
+    \ingroup creator-reference
+
+    \title Clang Code Model
+
+    \brief Offers code editing services for C++.
 
     The \e {code model} is the part of an IDE that understands the language you
     are using to write your application. It is the framework that allows \QC
@@ -73,7 +76,7 @@
 
         \li Code completion
         \li Syntactic and semantic highlighting
-        \li \l{Using Clang Tools}{Diagnostics}
+        \li \l{Clang Checks}{Diagnostics}
         \li Outline of symbols
         \li Tooltips
         \li Following symbols
@@ -84,17 +87,57 @@
 
     To use the built-in code model instead, select \preferences >
     \uicontrol C++ > \uicontrol clangd, and deselect the \uicontrol {Use clangd} check box.
-    This setting also exists on the project level, so that you can have the clang-based
+    This setting also exists on the project level, so that you can have the Clang-based
     services generally enabled, but switch them off for certain projects, or vice versa.
 
-    You can configure Clang diagnostics either globally or separately for:
+    You can configure Clang diagnostics for:
 
     \list
-        \li Clang code model (globally or at project level)
+        \li \l{Clang Checks}{Clang code model} (globally or at project level)
-        \li \l{Using Clang Tools}{Clang tools} (globally or at project level)
+        \li \l{Configure Clang diagnostics}{Clang tools} (globally or at project
+            level)
     \endlist
 
-    \section1 Configuring Clang Code Model
+    \section1 Clangd Indexing
+
+    The clangd \e index provides exact and complete results for services such
+    as finding references, following symbols under cursor, and using the
+    locator, even for complex constructs. When you \l{Open projects}
+    {open a project}, clangd scans the source files to generate the index. For
+    large projects, this can take a while, but the index is persistent and
+    re-scanning is incremental, so nothing is lost by closing and re-starting
+    \QC.
+
+    To temporarily disable global indexing, select
+    \uicontrol {Toggle Progress Details} (1), and then select \uicontrol X on
+    the progress bar.
+
+    \image qtcreator-toggle-progress-bar.webp {Toggle Progress Details button}
+
+    By default, \QC runs one clangd process per project. If you have created
+    \l{Manage sessions}{sessions} that have related projects, you can
+    specify that the projects in the session should be managed by a single
+    clangd process.
+
+    The document outline in the \l{Outline} view is backed by clangd's document
+    symbol support, which makes the results more reliable than before.
+
+    \sa {Code Model}, {Clangd}, {Specify clangd settings},
+    {Speficy Clang tools settings}, {Use compilation databases}
+*/
+
+/*!
+    \page creator-preferences-cpp-code-model.html
+    \previouspage creator-reference.html
+
+    \ingroup creator-reference-preferences-cpp
+
+    \title Code Model
+
+    \brief Sets global preferences for the code model.
+
+    The Clang code model offers services such as code completion, syntactic and
+    semantic highlighting, and diagnostics.
 
     To configure the Clang code model globally:
 
@@ -132,36 +175,29 @@
 
     \endlist
 
-    \section1 Configuring clangd
+    \sa {Specify clangd settings}, {Clang Code Model}, {Clangd}
+*/
 
-    The clangd \e index provides exact and complete results for services such
+/*!
-    as finding references, following symbols under cursor, and using the
+    \page creator-preferences-cpp-clangd.html
-    locator, even for complex constructs. When you \l{Open projects}
+    \previouspage creator-reference.html
-    {open a project}, clangd scans the source files to generate the index. For
-    large projects, this can take a while, but the index is persistent and
-    re-scanning is incremental, so nothing is lost by closing and re-starting
-    \QC.
 
-    To temporarily disable global indexing, select
+    \ingroup creator-reference-preferences-cpp
-    \uicontrol {Toggle Progress Details} (1), and then select \uicontrol X on
-    the progress bar.
 
-    \image qtcreator-toggle-progress-bar.webp {Toggle Progress Details button}
+    \title Clangd
 
-    By default, \QC runs one clangd process per project. If you have created
+    \brief Sets global preferences for the clangd code model.
-    \l{Manage sessions}{sessions} that have related projects, you can
-    specify that the projects in the session should be managed by a single
-    clangd process.
 
-    The document outline in the \l{Outline} view is backed by clangd's document
+    The Clang project has libraries for parsing C language family source files
-    symbol support, which makes the results more reliable than before.
+    and providing you with detailed diagnostics. The clangd \e index provides
+    exact and complete results for services such as code completion.
 
-    To specify settings for clangd:
+    To set preferences for clangd:
 
     \list 1
         \li Select \preferences > \uicontrol C++ >
             \uicontrol Clangd > \uicontrol {Use clangd}.
-            \image qtcreator-preferences-clangd.webp "Clangd preferences"
+            \image qtcreator-preferences-clangd.webp {Clangd preferences}
         \li In \uicontrol {Path to executable}, enter the path to clangd
             version 14, or later.
         \li In the \uicontrol {Background indexing} field, select \uicontrol Off
@@ -195,24 +231,30 @@
             by ignoring big files. Specify the maximum size of files to parse in
             the field next to the check box.
         \li The \uicontrol {Diagnostic configuration} field shows the Clang
-            checks to perform. Click the value of the field to open the
+            checks to perform. Click the value of the field to select and edit
-            \uicontrol {Diagnostic Configurations} dialog, where you can
+            the checks to perform.
-            select and edit the checks to perform.
         \li Select \uicontrol Add to select sessions that should use a single
             clangd process for indexing.
     \endlist
 
     \section1 Clang Checks
 
+    Click the value of the \uicontrol {Diagnostic configuration} field to open
+    the \uicontrol {Diagnostic Configurations} dialog, where you can select and
+    edit the checks to perform.
+
+    \image qtcreator-clang-diagnostic-configurations.webp {Diagnostic Configurations dialog}
+
     In addition to using the built-in checks, you can select \uicontrol Copy to
     create copies of them and edit the copies to fit your needs.
 
-    \uicontrol {Build-system warnings} displays warnings as specified
+    \list
-    by the build system.
+        \li \uicontrol {Build-system warnings} shows warnings as specified
-
+            by the build system.
-    \uicontrol {Checks for questionable constructs} combines the \c -Wall and
+        \li \uicontrol {Checks for questionable constructs} combines the \c -Wall
-    \c -Wextra checks for easily avoidable questionable constructions and some
+            and \c -Wextra checks for easily avoidable questionable constructions
-    additional issues.
+            and some additional issues.
+    \endlist
 
     Clang checks begin with \c -W. Each check also has a negative version that
     begins with \c -Wno.
@@ -221,11 +263,27 @@
     see \l{https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html}
     {Options to Request or Suppress Warnings} or the GCC or Clang manual pages.
 
-    \section1 Specifying Clang Code Model Settings at Project Level
+    \sa {Specify clangd settings}, {Clang Code Model}, {Code Model}
-
+*/
-    You can specify Clang code model settings at project level by selecting
+
-    \uicontrol Projects > \uicontrol {clangd}.
+/*!
-
+    \page creator-how-to-override-clangd-preferences.html
-    \include creator-compilation-database.qdocinc using compilation databases
+    \previouspage creator-how-tos.html
-
+
+    \ingroup creator-how-to-projects-configure
+
+    \title Specify clangd settings
+
+    To set clangd preferences for the current project:
+
+    \list 1
+        \li Select \uicontrol Projects > \uicontrol {Project Settings} >
+            \uicontrol {Clangd}.
+            \image qtcreator-projects-settings-clangd.webp {Clangd preferences for a project}
+        \li Deselect \uicontrol {Use global settings}.
+        \li Select \uicontrol {Use clangd}.
+        \li Specify \uicontrol Clangd preferences for the project.
+    \endlist
+
+    \sa {Clang Code Model}, {Clangd}, {Code Model}
 */

doc/qtcreator/src/editors/creator-only/creator-compilation-database.qdoc

@@ -1,10 +1,13 @@
-// Copyright (C) 2020 The Qt Company Ltd.
+// Copyright (C) 2024 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-//! [using compilation databases]
+    \page creator-how-to-use-compilation-databases.html
+    \previouspage creator-how-tos.html
 
-    \section1 Using Compilation Databases
+    \ingroup creator-how-to-build
+
+    \title Use compilation databases
 
     The \l{https://clang.llvm.org/docs/JSONCompilationDatabase.html}
     {JSON compilation database format} specifies how to replay single builds
@@ -34,7 +37,5 @@
     database projects in the \uicontrol Projects mode.
 
     \sa {Enable and disable plugins}, {Add custom build steps},
-    {Configure projects for running}
+    {Configure projects for running}, {Code Model}
-
-//! [using compilation databases]
 */

doc/qtcreator/src/editors/creator-quick-fixes.qdoc

@@ -153,13 +153,11 @@
     \section1 Summary of Refactoring Actions
 
     \if defined(qtcreator)
-    If you use the \l{Parsing C++ Files with the Clang Code Model}
+    If you use the \l{Clang Code Model}{Clang code model} to parse the C++ files,
-    {Clang code model} to parse the C++ files, the
+    you will get \l{http://clang.llvm.org/diagnostics.html}{Clang fix-it hints}
-    \l{http://clang.llvm.org/diagnostics.html}{Clang fix-it hints}
+    that have been integrated into \QC. Use the standard ways of activating
-    that have been integrated into \QC are also available to you. In addition to
+    refactoring actions or select the actions that are applicable on a line in
-    the standard ways of activating refactoring actions, you can select the
+    the context menu in the left margin of the code editor.
-    actions that are applicable on a line in the context menu in the left margin
-    of the code editor.
 
    \section2 Refactoring C++ Code
 

doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc

@@ -44,8 +44,7 @@
     generators. Their availability depends on the version of the build tool,
     host platform, and properties of the host system.
     Also, a JSON compilation database generator is available if the
-    \l{Parsing C++ Files with the Clang Code Model}{Clang Code Model plugin}
+    \l{Clang Code Model}{Clang Code Model plugin} is enabled (default).
-    is enabled (default).
 
     \section1 Set preferences for building and running
 

doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc

@@ -79,7 +79,7 @@
     the project:
 
             \list
-                \li \l{Parsing C++ Files with the Clang Code Model}{Clangd}
+                \li \l{Specify clangd settings}{Clangd}
                 \li \l{Using Clang Tools}{Clang Tools}
                 \li \l{Specify code style}{C++ Code Style}
                 \li \l{Set C++ file naming preferences}{C++ File Naming}

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -37,7 +37,6 @@
                 \li \l{Pasting and Fetching Code Snippets}
                 \li \l{Using Text Editing Macros}
                 \li \l{Comparing Files}
-                \li \l{Parsing C++ Files with the Clang Code Model}
             \endlist
             \li \l{Finding}
             \list