Doc: Edit information about Clang Code Model and Tools

Change-Id: I8482e34ce056dd9b6a5a20a0a7a2c7603ea9a4b0
Reviewed-by: Nikolai Kosjar <nikolai.kosjar@qt.io>

17 files changed, 148 insertions, 129 deletions

diff --git a/doc/images/qtcreator-clang-code-model-build-settings.png b/doc/images/qtcreator-clang-code-model-build-settings.png
index cc7d3d8cf9..05fa864b7c 100644
--- a/doc/images/qtcreator-clang-code-model-build-settings.png
+++ b/doc/images/qtcreator-clang-code-model-build-settings.png
diff --git a/doc/images/qtcreator-clang-code-model-options.png b/doc/images/qtcreator-clang-code-model-options.png
index 99351af363..1a42643d07 100644
--- a/doc/images/qtcreator-clang-code-model-options.png
+++ b/doc/images/qtcreator-clang-code-model-options.png
diff --git a/doc/images/qtcreator-clang-static-analyzer-options.png b/doc/images/qtcreator-clang-static-analyzer-options.png
deleted file mode 100644
index e12d71ffa6..0000000000
--- a/doc/images/qtcreator-clang-static-analyzer-options.png
+++ /dev/null
diff --git a/doc/images/qtcreator-clang-static-analyzer.png b/doc/images/qtcreator-clang-static-analyzer.png
deleted file mode 100644
index c9a1886ab0..0000000000
--- a/doc/images/qtcreator-clang-static-analyzer.png
+++ /dev/null
diff --git a/doc/images/qtcreator-clang-tidy.png b/doc/images/qtcreator-clang-tidy.png
index 156eb23d9d..bcf753b4f5 100644
--- a/doc/images/qtcreator-clang-tidy.png
+++ b/doc/images/qtcreator-clang-tidy.png
diff --git a/doc/images/qtcreator-clang-tools-options.png b/doc/images/qtcreator-clang-tools-options.png
new file mode 100644
index 0000000000..9a6cdc36d1
--- /dev/null
+++ b/doc/images/qtcreator-clang-tools-options.png
diff --git a/doc/images/qtcreator-clang-tools.png b/doc/images/qtcreator-clang-tools.png
new file mode 100644
index 0000000000..d1bd031788
--- /dev/null
+++ b/doc/images/qtcreator-clang-tools.png
diff --git a/doc/images/qtcreator-diagnostics-configuration.png b/doc/images/qtcreator-diagnostics-configuration.png
new file mode 100644
index 0000000000..736a749c60
--- /dev/null
+++ b/doc/images/qtcreator-diagnostics-configuration.png
diff --git a/doc/images/qtcreator-files-to-analyze.png b/doc/images/qtcreator-files-to-analyze.png
new file mode 100644
index 0000000000..f3ac5ad49d
--- /dev/null
+++ b/doc/images/qtcreator-files-to-analyze.png
diff --git a/doc/src/analyze/creator-analyze.qdoc b/doc/src/analyze/creator-analyze.qdoc
index 7e1a76e289..0b21852ab9 100644
--- a/doc/src/analyze/creator-analyze.qdoc
+++ b/doc/src/analyze/creator-analyze.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -65,11 +65,10 @@
             You can 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 Static Analyzer}{Clang Static Analyzer}
+        \li \l{Using Clang Tools}{Clang Tools}
 
-            You can detect problems in C, C++, and
-            Objective-C programs by using the experimental plugin that
-            integrates the Clang Static Analyzer source code analysis tool.
+            You can detect problems in C, C++, and Objective-C programs by
+            using Clang-Tidy and Clazy.
 
         \li \l{Detecting Memory Leaks with Heob}
 
diff --git a/doc/src/analyze/creator-clang-static-analyzer.qdoc b/doc/src/analyze/creator-clang-static-analyzer.qdoc
index 521b4da864..66ef1cd97c 100644
--- a/doc/src/analyze/creator-clang-static-analyzer.qdoc
+++ b/doc/src/analyze/creator-clang-static-analyzer.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -32,63 +32,113 @@
 /*!
     \contentspage {Qt Creator Manual}
     \previouspage creator-running-valgrind-remotely.html
-    \page creator-clang-static-analyzer.html
+    \page creator-clang-tools.html
     \nextpage creator-heob.html
 
-    \title Using Clang Static Analyzer
+    \title Using Clang Tools
 
-    \QC integrates the \l{http://clang-analyzer.llvm.org}
-    {Clang Static Analyzer} for finding problems in C, C++, and Objective-C
-    programs.
+    \QC integrates the following Clang tools for finding problems in C, C++, and
+    Objective-C source code by using static analysis:
 
-    \image qtcreator-clang-static-analyzer.png
+    \list
+
+        \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which
+            provides diagnostics and fixes for typical programming errors,
+            such as style violations or interface misuse.
+
+        \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which
+            helps Clang understand Qt semantics. It displays Qt related compiler
+            warnings, ranging from unnecessary memory allocation to misuse of
+            API and provides refactoring actions for fixing some of the issues.
+
+    \endlist
+
+    \note The Clang static analyzer checks are a part of Clang-Tidy. To use
+    the checks you must create a custom configuration for the Clang tools and
+    enable them for Clang-Tidy.
+
+    Clang tools are delivered and installed with \QC, and therefore you do not
+    need to set them up separately.
+
+    \section1 Running Clang Tools
+
+    To run the Clang tools to analyze an open project:
+
+    \list 1
+
+        \li Select \uicontrol Analyze > \uicontrol {Clang-Tidy and Clazy}.
+
+            \image qtcreator-files-to-analyze.png
+
+        \li In the \uicontrol {Diagnostic Configuration} group, select
+            \uicontrol Custom, and then select \uicontrol Manage to
+            specify the Clang-Tidy and Clazy checks to perform.
+
+        \li Select the new custom configuration in the list of configurations
+            (1).
+
+        \li In the \uicontrol {Files to Analyze} group, select the files to
+            apply the checks to.
+
+        \li Select \uicontrol Analyze to start the checks.
+
+    \endlist
+
+    If you select \uicontrol Debug in the mode selector to open the
+    \uicontrol Debug mode and then select \uicontrol {Clang-Tidy and Clazy},
+    you must select the \inlineimage qtcreator-analyze-start-button.png
+    (\uicontrol Start) button to open the \uicontrol {Analyzer Configuration}
+    dialog.
+
+    \image qtcreator-clang-tools.png
 
     Select the link in the \uicontrol Location column to move to the location
     where the issue appears in the code editor.
 
-    The Clang Static Analyzer runs with all the default checkers enabled. For
-    more information about the checkers, see
-    \l{http://clang-analyzer.llvm.org/available_checks.html}{Available Checkers}.
+    In the \uicontrol {Fixit Status} column, select issues that you want to
+    apply refactoring actions to, and then select \uicontrol {Apply Fixits}.
+    The status of the issues is updated in the \uicontrol {Fixit Status} column.
 
-    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 >
-    \uicontrol {Project Settings} > \uicontrol {Clang Static Analyzer}.
+    \section1 Configuring Clang Tools
+
+    To configure Clang diagnostics globally for Clang tools:
 
-    \section1 Supported Project Types and Tool Chains
+    \list
 
-    The Clang Static Analyzer relies on the data (specific macros and include
-    directories) from the projects and tool chains. Not all projects
-    and tool chains can provide enough data for reasonable results.
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer >
+            \uicontrol {Clang Tools} > \uicontrol Manage.
 
-    Currently, only Qbs and qmake projects together with the GCC, MinGW, Clang
-    and Microsoft Visual Studio tool chains are supported.
+            \image qtcreator-clang-tools-options.png
 
-    \section1 Setting Up Clang Static Analyzer
+        \li In the \uicontrol {Clang-Tidy} tab, select the checks to
+            perform.
 
-    As a tested version of Clang is shipped together with Qt Creator, no manual
-    setup is required.
+            \image qtcreator-clang-tidy.png
 
-    To profit from improved checkers in newer Clang versions, \QC can be set up
-    to use those. However, only the shipped version of Clang is tested and known
-    to work. Other versions might not work at all.
+        \li To edit the selected check as plain text, select
+            \uicontrol {Edit Checks as String}.
 
-    To set up a particular Clang version for the Clang Static Analyzer, select
-    \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer >
-    \uicontrol {Clang Static Analyzer} and check that the path to the Clang
-    executable is set correctly in the \uicontrol {Clang executable} field.
+        \li In the \uicontrol Clazy tab, select the level of Clazy
+            checks to perform.
+
+            \image qtcreator-clazy.png
+
+    \endlist
+
+    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 >
+    \uicontrol {Project Settings} > \uicontrol {Clang Tools}.
 
-    \image qtcreator-clang-static-analyzer-options.png
+    \section2 Selecting Clazy Check Levels
 
-    \section1 Running Clang Static Analyzer
+    The Clazy checks are divided into levels from 0 to 3. Each level adds checks
+    to the previous level. The checks at level 0 are very stable and provide
+    hardly any false positives, while the checks at level 3 can be considered
+    experimental.
 
-    To run the Clang Static Analyzer to analyze an open project, select
-    \uicontrol Analyze > \uicontrol {Clang Static Analyzer} on the menu bar. The
-    Clang Static Analyzer starts automatically.
+    For more information about the checks run at each level, see
+    \l{https://github.com/KDE/clazy/blob/master/README.md#list-of-checks}
+    {List of Checks} in the Clazy documentation.
 
-    However, if you select \uicontrol Debug in the mode selector to open the
-    \uicontrol Debug mode and then select \uicontrol {Clang Static Analyzer},
-    you must start the Clang Static Analyzer by selecting the
-    \inlineimage qtcreator-analyze-start-button.png
-    (\uicontrol Start) button.
 */
diff --git a/doc/src/analyze/creator-heob.qdoc b/doc/src/analyze/creator-heob.qdoc
index d8c2fae57c..3fba9aca8f 100644
--- a/doc/src/analyze/creator-heob.qdoc
+++ b/doc/src/analyze/creator-heob.qdoc
@@ -31,7 +31,7 @@
 
 /*!
     \contentspage {Qt Creator Manual}
-    \previouspage creator-clang-static-analyzer.html
+    \previouspage creator-clang-tools.html
     \page creator-heob.html
     \nextpage creator-cpu-usage-analyzer.html
 
diff --git a/doc/src/analyze/creator-valgrind.qdoc b/doc/src/analyze/creator-valgrind.qdoc
index ce1ed1f345..e52bd67d70 100644
--- a/doc/src/analyze/creator-valgrind.qdoc
+++ b/doc/src/analyze/creator-valgrind.qdoc
@@ -263,7 +263,7 @@
     \contentspage {Qt Creator Manual}
     \previouspage creator-cache-profiler.html
     \page creator-running-valgrind-remotely.html
-    \nextpage creator-clang-static-analyzer.html
+    \nextpage creator-clang-tools.html
 
     \title Running Valgrind Tools on External Applications
 
diff --git a/doc/src/editors/creator-clang-codemodel.qdoc b/doc/src/editors/creator-clang-codemodel.qdoc
index 92e786e518..c15717b956 100644
--- a/doc/src/editors/creator-clang-codemodel.qdoc
+++ b/doc/src/editors/creator-clang-codemodel.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -54,7 +54,9 @@
         \li Inspecting code by using the \l{Browsing Project Contents}
             {class browser}, the \l{Viewing QML Types}{outline}, and so on
 
-        \li Diagnostics and \l{Viewing Function Tooltips}{tooltips}
+        \li Diagnostics
+
+        \li \l{Viewing Function Tooltips}{Tooltips}
 
         \li \l{Finding Symbols}{Finding and renaming symbols}
 
@@ -85,79 +87,36 @@
     include several files, processing a single file and all the included files
     can take a while.
 
-    The Clang code model plugin replaces services of the old C/C++ code model.
-    Currently the following services are implemented:
+    The Clang code model plugin now provides some of the services that were
+    previously provided by the built-in C/C++ code model. Currently, the
+    following services are implemented:
 
     \list
 
         \li Code completion
         \li Syntactic and semantic highlighting
-        \li Diagnostics
-        \li Clang-Tidy checks
-        \li Clazy checks
+        \li \l{Using Clang Tools}{Diagnostics}
         \li Outline of symbols
         \li Tooltips
         \li Renaming of local symbols
 
     \endlist
 
-    \section1 Code Model Warnings
+    To use the built-in code model instead, select \uicontrol Help >
+    \uicontrol {About Plugins} > \uicontrol C++, and deselect the
+    \uicontrol ClangCodeModel check box. The changes take effect after
+    you restart \QC.
 
-    The predefined configurations request Clang warnings at the following
-    levels:
+    You can configure Clang diagnostics either globally or separately for:
 
     \list
-
-        \li \uicontrol {Pedantic Warnings} uses the \c -Wpendantic option that
-            requests all the warnings demanded by strict ISO C and ISO C++.
-
-        \li \uicontrol {Warnings for Questionable Constructs} combines the
-            \c -Wall and \c -Wextra options to request all warnings about easily
-            avoidable questionable constructions and some additional warnings.
-
-        \li \uicontrol {Warnings for Almost Everything} uses the \c -Weverything
-            option with negative options to suppress some warnings.
-
+        \li Clang code model (globally or at project level)
+        \li Clang tools (globally or at project level)
     \endlist
 
-    You can edit the predefined configurations to request specific warnings
-    beginning with \c -W. Each of these warnings also has a negative version
-    that begins with \c -Wno.
-
-    Keep in mind that some options turn on other options. For more information,
-    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 Using Clang-Tidy Checks
-
-    \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy} is delivered
-    as a part of the Clang library delivered with \QC. It provides diagnostics
-    and fixes for typical programming errors, such as style violations,
-    interface misuse, or issues that can be found via static analysis.
-
-    \QC integrates the fixes and diagnostics into the Clang library, and
-    therefore they cannot be easily changed or extended when used with \QC.
-
-    \section1 Using Clazy
-
-    \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy} is delivered
-    as a part of the Clang library delivered with \QC. It helps Clang understand
-    Qt semantics. It prints out Qt related compiler warnings, ranging from
-    unnecessary memory allocation to misuse of API and provides refactoring
-    actions for fixing some of the issues.
-
-    The Clazy checks are divided into levels from 0 to 3. Each level adds checks
-    to the previous level. The checks at level 0 are very stable and provide
-    hardly any false positives, while the checks at level 3 can be considered
-    experimental.
-
-    For more information about the checks run at each level, see
-    \l{https://github.com/KDE/clazy/blob/master/README.md#list-of-checks}
-    {List of Checks} in the Clazy documentation.
-
     \section1 Configuring Clang Code Model
 
-    To specify settings for the Clang code model:
+    To configure the Clang code model globally:
 
     \list 1
 
@@ -179,34 +138,46 @@
             edit the value for the \uicontrol {Do not index files greater than}
             check box. To index all files, deselect the check box.
 
-        \li In \uicontrol {Clang Dianostics}, select one of the predefined
-            configurations, or select \uicontrol Copy to create a copy of a
-            configuration and edit it to fit your needs.
+        \li Select \uicontrol Manage to specify the level for requesting Clang
+            warnings.
 
-            \list
+            \image qtcreator-diagnostics-configuration.png
 
-                \li In the \uicontrol Clang tab, edit the predefined
-                    configuration to request specific warnings.
+    \endlist
 
-                \li In the \uicontrol {Clang-Tidy} tab, select the checks to
-                    perform.
+    \section1 Clang Warnings
 
-                    \image qtcreator-clang-tidy.png
+    The predefined configurations request Clang warnings at the following
+    levels:
+
+    \list
 
-                \li In the \uicontrol Clazy tab, select the level of Clazy
-                    checks to perform.
+        \li \uicontrol {Pedantic Warnings} uses the \c -Wpendantic option that
+            requests all the warnings demanded by strict ISO C and ISO C++.
 
-                    \image qtcreator-clazy.png
+        \li \uicontrol {Warnings for Questionable Constructs} combines the
+            \c -Wall and \c -Wextra options to request all warnings about easily
+            avoidable questionable constructions and some additional warnings.
 
-            \endlist
+        \li \uicontrol {Warnings for Almost Everything} uses the \c -Weverything
+            option with negative options to suppress some warnings.
 
     \endlist
 
-    \section1 Specifying Clang Settings at Project Level
+    You can edit the predefined configurations to request specific warnings
+    beginning with \c -W. Each of these warnings also has a negative version
+    that begins with \c -Wno.
+
+    Keep in mind that some options turn on other options. For more information,
+    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
+
+    You can specify Clang code model settings at project level by selecting
+    \uicontrol Projects > \uicontrol {Clang Code Model}.
 
-    You can specify Clang settings at project level in the build settings of
-    the project by selecting \uicontrol Projects >
-    \uicontrol {Clang Code Model}. In addition to configuring the diagnostics,
+    In addition to configuring the diagnostics,
     you can select the \uicontrol {Enable MSVC-compliant template parsing} check
     box to parse templates in a MSVC-compliant way. This enables Clang to parse
     headers for example from Active Template Library (ATL) or Windows Runtime
diff --git a/doc/src/editors/creator-editors-writing-code.qdoc b/doc/src/editors/creator-editors-writing-code.qdoc
index fc358a9bd2..6524880a51 100644
--- a/doc/src/editors/creator-editors-writing-code.qdoc
+++ b/doc/src/editors/creator-editors-writing-code.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -111,11 +111,10 @@
 
         \li \l{Parsing C++ Files with the Clang Code Model}
 
-            A Clang code model plugin enables you to replace the
-            built-in \QC code model with the Clang code model. Clang is a C
-            language family front end for LLVM. Clang provides you with more
-            accurate information than the built-in code model but can be slower
-            to use for large projects.
+            The Clang code model provides some of the services previously
+            provided by 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.
 
     \endlist
 
diff --git a/doc/src/projects/creator-projects-settings-overview.qdoc b/doc/src/projects/creator-projects-settings-overview.qdoc
index 11e788951b..687a2df6d1 100644
--- a/doc/src/projects/creator-projects-settings-overview.qdoc
+++ b/doc/src/projects/creator-projects-settings-overview.qdoc
@@ -104,7 +104,7 @@
                 \li \l{Parsing C++ Files with the Clang Code Model}
                     {Clang Code Model}
 
-                \li \l{Using Clang Static Analyzer}{Clang Static Analyzer}
+                \li \l{Using Clang Tools}{Clang Tools}
 
                 \li \l{To-Do Entries}{To-Do} (experimental)
 
diff --git a/doc/src/qtcreator-toc.qdoc b/doc/src/qtcreator-toc.qdoc
index bda42932fb..f9e3907665 100644
--- a/doc/src/qtcreator-toc.qdoc
+++ b/doc/src/qtcreator-toc.qdoc
@@ -178,7 +178,7 @@
                     \li \l{Profiling Function Execution}
                     \li \l{Running Valgrind Tools on External Applications}
                 \endlist
-                \li \l{Using Clang Static Analyzer}
+                \li \l{Using Clang Tools}
                 \li \l{Detecting Memory Leaks with Heob}
                 \li \l{Analyzing CPU Usage}
             \endlist