Doc: Split up "Using Clang Tools"

Task-number: QTCREATORBUG-29361
Change-Id: If33dbd417575b584836927ff866e2cd1ec20ba70
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

doc/qtcreator/src/analyze/creator-analyze.qdoc

@@ -54,7 +54,7 @@
             Detect problems in memory management by using the Memcheck
             tool and find cache misses in the code by using the Callgrind tool.
 
-        \li \l{Using Clang Tools}{Clang Tools}
+        \li \l{Clang Tools}
 
             Detect problems in C, C++, and Objective-C programs by
             using Clang-Tidy and Clazy.

doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc

@@ -1,4 +1,4 @@
-// Copyright (C) 2023 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,13 +8,14 @@
 // **********************************************************************
 
 /*!
-    \previouspage creator-running-valgrind-remotely.html
     \page creator-clang-tools.html
-    \nextpage creator-heob.html
+    \previouspage creator-how-tos.html
 
-    \title Using Clang Tools
+    \ingroup creator-how-to-analyze
 
-    \QC integrates the following Clang tools for finding problems in C, C++, and
+    \title Analyze code with Clang-Tidy and Clazy
+
+    \QC comes with the following Clang tools for finding problems in C, C++, and
     Objective-C source code by using static analysis:
 
     \list
@@ -34,14 +35,7 @@
     the checks, you must create a custom configuration for the Clang tools and
     enable them for Clang-Tidy.
 
-    \QC comes with the Clang tools, so you do not need to set them up separately.
-
-    In addition to running the tools to collect diagnostics, you can select
-    \inlineimage icons/open.png
-    to load diagnostics from \l{https://yaml.org/}{YAML} files that you exported
-    using the \c {-export fixes} option.
-
-    \section1 Running Clang-Tidy and Clazy
+    \section1 Analyze the current file
 
     To run Clang-Tidy or Clazy to analyze the currently open file:
 
@@ -54,6 +48,8 @@
             \uicontrol {Analyze Current File with Clazy}.
     \endlist
 
+    \section1 Analyze an open project
+
     To run Clang-Tidy or Clazy to analyze an open project:
 
     \list 1
@@ -69,9 +65,12 @@
 
     \endlist
 
+    \section1 View diagnostics
+
     The \uicontrol {Clang-Tidy} or \uicontrol {Clazy} view shows the issues:
 
     \image qtcreator-clang-tidy-view.webp {Clang-Tidy view}
+    \caption Diagnostics in the Clang-Tidy view.
 
     \note If you select \uicontrol Debug in the mode selector to open the
     \uicontrol Debug mode and then select \uicontrol {Clang-Tidy} or
@@ -91,21 +90,68 @@
     \inlineimage icons/refactormarker.png
     icon, hover the mouse pointer over the line.
 
+    Select the \inlineimage icons/settings.png
+    button to customize diagnostics for the current project.
+
+    \section1 Disable checks
+
     To disable checks of a particular type either globally or for a
     particular project, select \uicontrol {Disable This Check} or
     \uicontrol {Disable These Checks} in the context menu.
 
-    Select the \inlineimage icons/settings.png
-    button to customize Clang diagnostics for the current project.
+    \section1 Load diagnostics from YAML files
 
+    In addition to running the tools to collect diagnostics, you can select
+    \inlineimage icons/open.png
+    to load diagnostics from \l{https://yaml.org/}{YAML} files that you exported
+    using the \c {-export fixes} option.
+
+    \sa {Configure Clang Diagnostics}, {Speficy Clang tools settings},
+    {Clang Tools}
+*/
+
+/*!
+    \page creator-how-to-override-clang-tools-preferences.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-projects-configure
+
+    \title Speficy Clang tools settings
+
+    To set Clang-Tidy and Clazy checks to run for the current project:
+
+    \list 1
+        \li Select \uicontrol Projects > \uicontrol {Project Settings} >
+            \uicontrol {Clang Tools}.
             \image qtcreator-clang-tools-settings.webp {Clang Tools customized settings}
+        \li Deselect \uicontrol {Use global settings}.
+        \li Specify \uicontrol preferences for the project.
+        \li In \uicontrol {Suppressed diagnostics}, you can view the suppression
+            list for a project and to remove diagnostics from it.
+    \endlist
 
     To restore the global settings, select \uicontrol {Restore Global Settings}.
     To view and modify the global settings, select the link in
-    \uicontrol {Use global settings}. To open the Clang static analyzer,
-    select \uicontrol {Go to Analyzer}.
+    \uicontrol {Use global settings}.
 
-    \section1 Configuring Clang Tools
+    To open the \uicontrol Clang-Tidy view, select \uicontrol {Go to Clang-Tidy}.
+    To open the \uicontrol Clazy view, select \uicontrol {Go to Clazy}.
+
+    \sa {Configure Clang diagnostics}, {Analyze code with Clang-Tidy and Clazy}, {Clang Tools}
+*/
+
+/*!
+    \page creator-preferences-analyzer-clang-tools.html
+    \previouspage creator-reference.html
+
+    \ingroup creator-reference-preferences-analyzer
+
+    \title Clang Tools
+
+    \brief Set preferences for Clang-Tidy and Clazy.
+
+    Detect problems in C, C++, and Objective-C programs with Clang-Tidy
+    and Clazy.
 
     To configure Clang diagnostics globally for Clang tools:
 
@@ -119,6 +165,14 @@
         \li In the \uicontrol Clang-Tidy and \uicontrol Clazy-Standalone fields,
             set the paths to the executables to use.
 
+        \li The \uicontrol {Diagnostic configuration} field shows the
+            checks to perform. Click the value of the field to open the
+            \uicontrol {Diagnostic Configurations} dialog, where you can
+            select and edit the checks to perform.
+
+            To perform checks from a Clang-Tidy configuration file instead,
+            select \uicontrol {Prefer .clang-tidy file, if present}.
+
         \li To build the project before running the Clang tools, select the
             \uicontrol {Build the project before analysis} check box. The Clang
             tools do not require that you build the project before analysis, but
@@ -132,6 +186,31 @@
         \li In the \uicontrol {Parallel jobs} field, select the number of jobs
             to run in parallel to make the analysis faster on multi-core
             processors.
+    \endlist
+
+    \sa {Configure Clang diagnostics}, {Analyze code with Clang-Tidy and Clazy},
+    {Speficy Clang tools settings}
+*/
+
+/*!
+    \page creator-how-to-configure-clang-diagnostics.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-analyze
+
+    \title Configure Clang diagnostics
+
+    Detect problems in C, C++, and Objective-C programs with Clang-Tidy
+    and Clazy.
+
+    To select and edit the Clang checks to perform:
+
+    \list 1
+
+        \li Select \preferences > \uicontrol Analyzer >
+            \uicontrol {Clang Tools}.
+
+            \image qtcreator-preferences-analyzer-clang-tools.webp {Clang Tools preferences}
 
         \li The \uicontrol {Diagnostic configuration} field shows the
             checks to perform. Click the value of the field to open the
@@ -140,7 +219,7 @@
 
             \image qtcreator-clang-tools-diagnostics-configuration.png {Diagnostics Configuration dialog}
 
-            To perform checks from a Clang Tidy configuration file instead,
+            To perform checks from a Clang-Tidy configuration file instead,
             select \uicontrol {Prefer .clang-tidy file, if present} in the
             \uicontrol {Clang Tools} tab.
 
@@ -188,6 +267,8 @@
 
     \endlist
 
+    \section2 Suppressing Diagnostics
+
     To suppress diagnostics, select \uicontrol {Suppress This Diagnostic} in the
     context menu. To view the suppression list for a project and to remove
     diagnostics from it, select \uicontrol Projects >
@@ -225,4 +306,6 @@
     To add more checks using \QC later on, copy the checks from your .clang-tidy
     file into the \uicontrol {Edit Checks as String} field, select additional
     checks, and copy-paste the contents of the field to the .clang-tidy file.
+
+    \sa {Analyze code with Clang-Tidy and Clazy}, {Speficy Clang tools settings}, {Clang Tools}
 */

doc/qtcreator/src/overview/creator-only/creator-reference.qdoc

@@ -35,6 +35,10 @@
 
     \annotatedlist creator-reference-preferences
 
+    \section2 Analyzer
+
+    \annotatedlist creator-reference-preferences-analyzer
+
     \section2 C++
 
     \annotatedlist creator-reference-preferences-cpp

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

@@ -80,7 +80,7 @@
 
             \list
                 \li \l{Specify clangd settings}{Clangd}
-                \li \l{Using Clang Tools}{Clang Tools}
+                \li \l{Speficy Clang tools settings}{Clang Tools}
                 \li \l{Specify code style}{C++ Code Style}
                 \li \l{Set C++ file naming preferences}{C++ File Naming}
                 \li \l{Specify dependencies}{Dependencies}

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -128,7 +128,6 @@
                     \li \l{Profiling Function Execution}
                     \li \l{Running Valgrind Tools on External Applications}
                 \endlist
-                \li \l{Using Clang Tools}
                 \li \l{Detecting Memory Leaks with Heob}
                 \li \l{Analyzing CPU Usage}
                 \li \l{Analyzing Code with Cppcheck}
@@ -190,6 +189,8 @@
                     \li Preferences
                         \generatelist creator-reference-preferences
                         \list
+                            \li Analyzer
+                                \generatelist creator-reference-preferences-analyzer
                             \li C++
                                 \generatelist creator-reference-preferences-cpp
                             \li Text editor