Doc: Add descriptive text for how-to and reference topic categories

- Move some topics to other categories.
- Edit some \brief text for consistency.

Task-number: QTCREATORBUG-29361
Change-Id: I37d0ff5aef6121e1c3bc552fb802188271f4b913
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

10 files changed, 113 insertions, 21 deletions

diff --git a/doc/qtcreator/src/editors/creator-code-syntax.qdoc b/doc/qtcreator/src/editors/creator-code-syntax.qdoc
index aa5e01f125..f20ecadb8e 100644
--- a/doc/qtcreator/src/editors/creator-code-syntax.qdoc
+++ b/doc/qtcreator/src/editors/creator-code-syntax.qdoc
@@ -103,7 +103,7 @@
     \previouspage creator-reference.html
     \endif
 
-    \ingroup creator-reference-editors
+    \ingroup creator-reference-analyzer
     \ingroup studio-how-to-code
 
     \title JavaScript and QML Checks
diff --git a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc
index 99bad72d10..f07a79e986 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc
@@ -11,7 +11,7 @@
     \page creator-clang-codemodel.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-editors
 
     \title Clang Code Model
 
diff --git a/doc/qtcreator/src/editors/creator-only/creator-cpp-quick-fixes.qdoc b/doc/qtcreator/src/editors/creator-only/creator-cpp-quick-fixes.qdoc
index 44cc63bbf6..b3bab5c7fe 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-cpp-quick-fixes.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-cpp-quick-fixes.qdoc
@@ -78,7 +78,7 @@
     \page creator-reference-cpp-quick-fixes.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-editors
 
     \title C++ Quick Fixes
 
diff --git a/doc/qtcreator/src/editors/creator-only/creator-fakevim.qdoc b/doc/qtcreator/src/editors/creator-only/creator-fakevim.qdoc
index 63295aa114..db152c0e1d 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-fakevim.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-fakevim.qdoc
@@ -31,7 +31,7 @@
     \page creator-editor-fakevim.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-editors
 
     \title FakeVim Modes and Commands
 
diff --git a/doc/qtcreator/src/editors/creator-only/creator-modeling.qdoc b/doc/qtcreator/src/editors/creator-only/creator-modeling.qdoc
index d42cbc4d35..426cc25d67 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-modeling.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-modeling.qdoc
@@ -11,11 +11,11 @@
     \page creator-modeling.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-editors
 
     \title Model Editor
 
-    \brief Editor for Universal Modeling Language (UML) style models with
+    \brief Create Universal Modeling Language (UML) style models with
     structured and behavioral diagrams.
 
     Use the model editor to create Universal Modeling Language (UML)
diff --git a/doc/qtcreator/src/editors/creator-only/creator-scxml.qdoc b/doc/qtcreator/src/editors/creator-only/creator-scxml.qdoc
index eac59c4740..80ffbe8ab2 100644
--- a/doc/qtcreator/src/editors/creator-only/creator-scxml.qdoc
+++ b/doc/qtcreator/src/editors/creator-only/creator-scxml.qdoc
@@ -11,11 +11,11 @@
     \page creator-scxml.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-editors
 
     \title SCXML Editor
 
-    \brief State chart (.scxml) editor.
+    \brief Edit state chart (.scxml) files.
 
     State charts are a graphical way of modeling how a system reacts to
     stimuli. They define the \e states that the system can
diff --git a/doc/qtcreator/src/editors/creator-quick-fixes.qdoc b/doc/qtcreator/src/editors/creator-quick-fixes.qdoc
index 964b813480..7e02f60c65 100644
--- a/doc/qtcreator/src/editors/creator-quick-fixes.qdoc
+++ b/doc/qtcreator/src/editors/creator-quick-fixes.qdoc
@@ -106,7 +106,7 @@
     \endif
 
     \ingroup creator-reference-editors
-    \ingroup studio-how-to-refactor-code
+    \ingroup studio-code-view
 
     \title QML Quick Fixes
 
diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc
index 11adddb54d..1b545943e3 100644
--- a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc
+++ b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc
@@ -18,8 +18,8 @@
 
     \section1 Analyze
 
-    \QC integrates code analysis tools for detecting memory leaks, profiling
-    function execution, analyzing CPU use, and eliminating unnecessary
+    Use integrated code analysis tools to detect memory leaks, profile
+    function execution, analyze CPU use, and eliminate unnecessary
     complexity of code. Other integrated tools provide code coverage and
     visualize trace events.
 
@@ -27,36 +27,66 @@
 
     \section1 Build and Run
 
+    Use integrated cross-platform systems for build automation to compile your
+    source code for different target platforms or with different compilers,
+    debuggers, or Qt versions. Deploy applications to the target platforms
+    and run them there.
+
     \generatelist creator-how-to-build
 
     \section2 Build with CMake
 
+    CMake controls the software compilation process by using simple configuration
+    files, called \e CMakeLists.txt files.
+
     \generatelist creator-how-to-build-with-cmake
 
     \section2 Build with qmake
 
+    qmake automates the generation of Makefiles based on the information in a
+    project file that has the extension \e .pro.
+
     \generatelist creator-how-to-build-with-qmake
 
     \section2 Run applications
 
+    Run applications on local and remote desktop systems, as well as on
+    embedded and mobile devices that you connect to the computer.
+
     \generatelist creator-how-to-run
 
     \section1 Create Models and Diagrams
 
+    Create Universal Modeling Language (UML) style models with structured and
+    behavioral diagrams that offer different views to your system. Or, use a
+    file wizard to create State Chart XML (SCXML) files with boilerplate code
+    and edit them with an SCXML editor.
+
     \generatelist creator-how-to-models
 
     \section1 Debug
 
+    Use native debuggers to inspect the state of your application while
+    debugging.
+
     \generatelist creator-how-to-debug
 
     \section1 Design UIs
 
+    Design UIs with either \l{User Interfaces}{Qt Quick or Qt Widgets}.
+    \QC integrates a visual editor, \QD, for designing widget-based UIs
+    in the \uicontrol Design mode. For Qt Quick UIs, use a separate visual
+    editor, \l{\QDS Manual}{\QDS}, or the \uicontrol Edit mode.
+
     \generatelist creator-how-to-design
 
     \section1 Edit Code
 
-    The code editor offers useful features, such as semantic highlighting,
-    checking code syntax, code completion, and refactoring actions.
+    The code editor offers useful features for editing C++ and QML code, such
+    as semantic highlighting, checking code syntax, code completion, and quick
+    fixes. Some of these features are also for other programming languages, such
+    as Python, for which a \e {language server} is available that provides
+    information about the code to IDEs.
 
     \generatelist creator-how-to-edit
 
@@ -69,39 +99,64 @@
 
     \section2 Manage Language Servers
 
+    Configure language servers that \QC adds by default or add more of them.
+
     \generatelist creator-how-to-lsp
 
     \section2 Search
 
+    Use the incremental and advanced search to search in currently open projects
+    or files on the file system or use the locator to browse through projects,
+    files, classes, functions, documentation, and file systems.
+
     \generatelist creator-how-to-search
 
     \section1 Manage Kits
 
+    \QC groups build and run specific settings as kits to make cross-platform
+    development easier. Each kit consists of a set of values that define one
+    environment, such as a device, tool chain, Qt version, and debugger command
+    to use.
+
     \generatelist creator-how-to-manage-kits
 
     \section1 Manage Projects
 
+    Create projects for developing applications and libraries. Then configure
+    the projects for building and running the applications on target platforms.
+
     \generatelist creator-how-to-projects
 
     \section2 Create Projects
 
+    Use preset wizards to create projects or add custom wizards. You can also
+    import projects from version control systems.
+
     \generatelist creator-how-to-projects-create
 
     \section2 Add Files
 
+    Add files to projects.
+
     \generatelist creator-how-to-projects-files
 
     \section2 Configure Projects
 
+    Change the default configurations that installation programs and project
+    wizards create.
+
     \generatelist creator-how-to-projects-configure
 
     \section1 Read Documentation
 
+    \QC integrates the reference documentation for the Qt versions that you
+    install. You can add documentation from other sources.
+
     \generatelist creator-how-to-get-help
 
     \section1 Test
 
-    \QC supports both \e {code based tests} and \e {build system based tests}.
+    Create and run \e {code based tests} and \e {build system based tests}.
     Code based testing offers special handling for particular testing
     frameworks that strongly ties to the underlying code models or
     specialized parsers. Build system based testing is independent from any
@@ -113,10 +168,15 @@
 
     \section1 Use \QC
 
+    Use basic \QC features and preinstalled plugins. Install more plugins and
+    configure external tools for use.
+
     \generatelist creator-how-to-use
 
     \section1 Use the UI
 
+    Navigate the UI or change its appearance and behavior.
+
     \generatelist creator-how-to-ui
 */
 
diff --git a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc
index 1fe8e41e28..0a9240f759 100644
--- a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc
+++ b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc
@@ -8,12 +8,21 @@
 
     \title Reference
 
+    The following topics contain reference information about using \QC and the
+    integrated tools.
+
     \annotatedlist creator-reference
 
+    \section1 Analyzers
+
+    Use integrated code analysis tools to improve your C++ or QML code.
+
+    \annotatedlist creator-reference-analyzer
+
     \section1 Build Systems
 
-    Most \QC project wizards enable you to choose the build system to use for
-    building the project: qmake, CMake, Meson, or Qbs. qmake is installed and
+    When you create projects, you can choose the build system to use for
+    building the project: CMake, qmake, Meson, or Qbs. qmake is installed and
     configured when you install Qt. To use one of the other supported build
     systems, you need to set it up.
 
@@ -29,33 +38,46 @@
 
     \section1 Editors
 
+    When you open files, \QC chooses a suitable editor according to the file
+    type.
+
     \annotatedlist creator-reference-editors
 
     \section1 Platforms
 
+    You can install and run \QC on several operating systems to create
+    applications for multiple desktop, embedded, and mobile device platforms.
+
     \annotatedlist creator-reference-platforms
 
     \section1 Preferences
 
-    Set preferences that apply globally to all projects.
+    You can set preferences that apply globally to all projects and override
+    them for particular projects.
 
     \annotatedlist creator-reference-preferences
 
     \section2 Analyzer
 
+    Preferences for code analysis tools.
+
     \annotatedlist creator-reference-preferences-analyzer
 
     \section2 C++
 
+    Preferences for editing C++ code.
+
     \annotatedlist creator-reference-preferences-cpp
 
     \section2 Kits
 
+    Preferences for build and run kits.
+
     \annotatedlist creator-reference-preferences-kits
 
     \section2 Text Editor
 
-    Configure the text editor to suit your needs.
+    Preferences for the behavior and appearance of text and code editors.
 
     \annotatedlist creator-reference-preferences-text-editor
 
@@ -72,8 +94,7 @@
 
     \section1 UI Design
 
-    Design UIs with either \l{User Interfaces}{Qt Quick or Qt Widgets}.
-    \QC integrates a visual editor, \QD, for designing widget-based UIs
+    You can use a visual editor, \QD, for designing widget-based UIs
     in the \uicontrol Design mode. For Qt Quick UIs, use a separate visual
     editor, \l{\QDS Manual}{\QDS}, or the \uicontrol Edit mode.
 
@@ -81,11 +102,22 @@
 
     \section1 Views
 
+    When you switch modes or trigger actions, \QC opens views for viewing
+    output and organizing project contents.
+
     \section2 Output Views
 
+    You can view output from several sources, such as a list of errors and
+    warnings encountered during a build, detailed output from the compiler,
+    status of a program when it is executed, debug output, or search results.
+
     \annotatedlist creator-reference-output-views
 
     \section2 Sidebar Views
 
+    In some modes, you can use a left and right sidebar to organize different
+    views into project contents. Only views that are relevant to the mode you
+    are working in are available in it.
+
     \annotatedlist creator-reference-sidebar-views
 */
diff --git a/doc/qtcreator/src/overview/creator-only/mobile-app-design.qdoc b/doc/qtcreator/src/overview/creator-only/mobile-app-design.qdoc
index 1697c2d51c..d65a1e904c 100644
--- a/doc/qtcreator/src/overview/creator-only/mobile-app-design.qdoc
+++ b/doc/qtcreator/src/overview/creator-only/mobile-app-design.qdoc
@@ -11,7 +11,7 @@
     \page creator-usability.html
     \previouspage creator-reference.html
 
-    \ingroup creator-reference
+    \ingroup creator-reference-platforms
 
     \title Optimizing Applications for Mobile Devices