Doc: Edit information about Clang Code Model and Tools

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

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}
 

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.
+
+    \section1 Configuring Clang Tools
+
+    To configure Clang diagnostics globally for Clang tools:
+
+    \list
+
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer >
+            \uicontrol {Clang Tools} > \uicontrol Manage.
+
+            \image qtcreator-clang-tools-options.png
+
+        \li In the \uicontrol {Clang-Tidy} tab, select the checks to
+            perform.
+
+            \image qtcreator-clang-tidy.png
+
+        \li To edit the selected check as plain text, select
+            \uicontrol {Edit Checks as String}.
+
+        \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 Static Analyzer}.
+    \uicontrol {Project Settings} > \uicontrol {Clang Tools}.
 
-    \section1 Supported Project Types and Tool Chains
+    \section2 Selecting Clazy Check Levels
 
-    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.
+    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.
 
-    Currently, only Qbs and qmake projects together with the GCC, MinGW, Clang
-    and Microsoft Visual Studio tool chains are supported.
+    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 Setting Up Clang Static Analyzer
-
-    As a tested version of Clang is shipped together with Qt Creator, no manual
-    setup is required.
-
-    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.
-
-    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.
-
-    \image qtcreator-clang-static-analyzer-options.png
-
-    \section1 Running Clang Static Analyzer
-
-    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.
-
-    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.
 */

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
 

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
 

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,23 +87,65 @@
     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.
+
+    You can configure Clang diagnostics either globally or separately for:
+
+    \list
+        \li Clang code model (globally or at project level)
+        \li Clang tools (globally or at project level)
+    \endlist
+
+    \section1 Configuring Clang Code Model
+
+    To configure the Clang code model globally:
+
+    \list 1
+
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol C++ >
+            \uicontrol {Code Model}.
+
+            \image qtcreator-clang-code-model-options.png
+
+        \li To instruct the code model to interpret ambiguous header files as C
+            language files if you develop mainly using C, select the
+            \uicontrol {Interpret ambiguous headers as C headers} check box.
+
+        \li To process precompiled headers, deselect the
+            \uicontrol {Ignore precompiled headers} check box.
+
+        \li To avoid out-of-memory crashes caused by indexing huge source files
+            that are typically auto-generated by scripts or code, the size of
+            files to index is limited to 5MB by default. To adjust the limit,
+            edit the value for the \uicontrol {Do not index files greater than}
+            check box. To index all files, deselect the check box.
+
+        \li Select \uicontrol Manage to specify the level for requesting Clang
+            warnings.
+
+            \image qtcreator-diagnostics-configuration.png
+
+    \endlist
+
+    \section1 Clang Warnings
 
     The predefined configurations request Clang warnings at the following
     levels:
@@ -128,85 +172,12 @@
     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
+    \section1 Specifying Clang Code Model Settings at Project Level
 
-    \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.
+    You can specify Clang code model settings at project level by selecting
+    \uicontrol Projects > \uicontrol {Clang Code Model}.
 
-    \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:
-
-    \list 1
-
-        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol C++ >
-            \uicontrol {Code Model}.
-
-            \image qtcreator-clang-code-model-options.png
-
-        \li To instruct the code model to interpret ambiguous header files as C
-            language files if you develop mainly using C, select the
-            \uicontrol {Interpret ambiguous headers as C headers} check box.
-
-        \li To process precompiled headers, deselect the
-            \uicontrol {Ignore precompiled headers} check box.
-
-        \li To avoid out-of-memory crashes caused by indexing huge source files
-            that are typically auto-generated by scripts or code, the size of
-            files to index is limited to 5MB by default. To adjust the limit,
-            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.
-
-            \list
-
-                \li In the \uicontrol Clang tab, edit the predefined
-                    configuration to request specific warnings.
-
-                \li In the \uicontrol {Clang-Tidy} tab, select the checks to
-                    perform.
-
-                    \image qtcreator-clang-tidy.png
-
-                \li In the \uicontrol Clazy tab, select the level of Clazy
-                    checks to perform.
-
-                    \image qtcreator-clazy.png
-
-            \endlist
-
-    \endlist
-
-    \section1 Specifying Clang Settings at Project Level
-
-    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

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
 

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)
 

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