Doc: Split "Completing Code" into several topics

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

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

@@ -235,7 +235,7 @@
     Warnings and errors are displayed in \l {Issues}.
 
     \sa {CMake}, {Add libraries to CMake projects}, {Complete CMake code},
-    {Completing Code Snippets}, {Format CMake files}
+    {Format CMake files}, {Completion}, {Snippets}
 */
 
 /*!
@@ -260,8 +260,10 @@
         \li \c{$ENV} for environment variables
     \endlist
 
-    \sa {CMake}, {Completing Code}, {Completing Code Snippets},
+    Press \key Tab or \key Enter to accept the selected suggestion and complete
-    {Edit CMake configuration files}
+    the code.
+
+    \sa {CMake}, {Edit CMake configuration files}, {Completion}, {Snippets}
 */
 
 /*!
@@ -364,7 +366,7 @@
     For CMake projects that have external dependencies, use
     \l{CMake: Find Modules}{Find<package>.cmake} modules that
     expose imported targets. You can use the pre-defined \c sample_find_module
-    \l{Completing Code Snippets}{code snippet} to add sample commands
+    \l{Snippets}{code snippet} to add sample commands
     to a \c .cmake file. You can then change the commands as necessary.
 
     Place Find modules in the \c ${CMAKE_CURRENT_SOURCE_DIR}/cmake directory, and
@@ -376,5 +378,5 @@
     \endcode
 
     \sa {CMake}, {Edit CMake configuration files}, {Complete CMake code},
-    {Completing Code Snippets}
+    {Completion}, {Snippets}
 */

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

@@ -1,64 +1,36 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-    \previouspage creator-checking-code-syntax.html
     \page creator-completing-code.html
-    \nextpage creator-indenting-code.html
+    \if defined(qtdesignstudio)
+    \previouspage creator-editor-functions.html
+    \else
+    \previouspage creator-how-tos.html
+    \endif
 
-    \title Completing Code
+    \ingroup creator-how-to-edit
+
+    \title Complete code
 
     As you write code, \QC suggests properties, IDs, and code snippets to
     complete the code. It shows a list of suggestions to
-    the statement currently under your cursor. Press \key Tab
+    the statement currently under your cursor.
-    or \key Enter to accept the selected suggestion and complete the code.
+
+    Press \key Tab or \key Enter to accept the selected suggestion and complete
+    the code.
 
     \if defined(qtcreator)
-    The following image displays suggestions for completing C++ code:
-
     \image qtcreator-codecompletion.png
+    \caption Suggestions for completing C++ code.
     \endif
 
-    The following image displays suggestions for completing QML code:
-
     \image qml-code-completion.png
+    \caption Suggestions for completing QML code.
 
     To open the list of suggestions at any time, press \key {Ctrl+Space}.
     If only one option is available, \QC inserts it automatically.
 
-    \section1 Specifying Completion Settings
-
-    To specify settings for code completion, select \preferences >
-    \uicontrol {Text Editor} > \uicontrol Completion.
-
-    \image qtcreator-preferences-texteditor-completion.webp "Text Editor Completion preferences"
-
-    By default, code completion does not consider case. To apply full or
-    first-letter case-sensitivity, select \uicontrol Full or
-    \uicontrol {First Letter} in the \uicontrol {Case-sensitivity} field.
-
-    By default, code completion is always invoked, but you can change this
-    behavior in the \uicontrol {Activate completion} field to invoke
-    it \uicontrol Manually or \uicontrol {When Triggered}.
-
-    You can set a timeout in milliseconds for code completion in the
-    \uicontrol {Timeout in ms} field.
-
-    In the \uicontrol {Character threshold} field, specify the number of
-    characters you need to enter before code completion is triggered.
-
-    When completion is invoked manually, \QC completes the common prefix of the
-    list of suggestions. This is especially useful for classes with several
-    similarly named members. To disable this functionality, deselect the
-    \uicontrol {Autocomplete common prefix} check box.
-
-    Select the \uicontrol {Automatically split strings} check box to split
-    a string to two lines by adding an end quote at the cursor position when
-    you press \key Enter and a start quote at the beginning of the next line,
-    before the rest of the string. In addition, pressing \key {Shift+Enter}
-    inserts an escape character at the cursor position and moves the rest of
-    the string to the next line.
-
     \section1 Summary of Available Types
 
     The following table lists available types for code completion and icon used
@@ -131,7 +103,7 @@
         \endif
     \endtable
 
-    \section1 Completing Code Snippets
+    \section1 Complete code snippets
 
     Code snippets can consist of multiple variables that you specify values for.
     Select an item in the list and press \key Tab or \key Enter to complete the
@@ -140,71 +112,129 @@
     within the snippet are renamed.
 
     \if defined(qtcreator)
-    The following image shows a C++ code snippet:
-
     \image qmldesigner-code-completion.png "Completing C++ code"
+    \caption C++ code snippet.
     \endif
 
-    The following image shows a QML code snippet:
-
     \image qml-code-snippet.png
-
+    \caption QML code snippet.
-    \section2 Editing Code Snippets
-
-    Code snippets specify code constructs. You can add, modify,
-    and remove snippets in the snippet editor. To open the editor, select
-    \preferences > \uicontrol {Text Editor} >
-    \uicontrol Snippets.
 
     \if defined(qtcreator)
-    The following image shows built-in C++ code snippets:
+    \sa {Complete CMake code}, {Nim}
-
-    \image qtcreator-edit-code-snippets.png "C++ snippet preferences"
     \endif
 
-    The following image shows built-in QML code snippets:
+    \sa {Add code snippets to the auto-complete menu}, {Completion}, {Snippets}
+*/
 
-    \image qml-snippet-editor.png
+/*!
+    \page creator-preferences-text-editor-completion.html
+    \if defined(qtdesignstudio)
+    \previouspage creator-completing-code.html
+    \else
+    \previouspage creator-reference.html
+    \endif
+
+    \ingroup creator-reference-preferences-text-editor
+
+    \title Completion
+
+    \brief Set preferences for code completion and inserting matching characters
+    in the text editor.
+
+    To set preferences for code completion, select \preferences >
+    \uicontrol {Text Editor} > \uicontrol Completion.
+
+    \image qtcreator-preferences-texteditor-completion.webp {Text Editor Completion preferences}
+
+    \section1 Code Completion Behavior
+
+    By default, code completion does not consider case. To apply full or
+    first-letter case-sensitivity, select \uicontrol Full or
+    \uicontrol {First Letter} in the \uicontrol {Case-sensitivity} field.
+
+    By default, code completion is always invoked, but you can change this
+    behavior in the \uicontrol {Activate completion} field to invoke
+    it \uicontrol Manually or \uicontrol {When Triggered}.
+
+    You can set a timeout in milliseconds for code completion in the
+    \uicontrol {Timeout in ms} field.
+
+    In the \uicontrol {Character threshold} field, specify the number of
+    characters you need to enter before code completion is triggered.
+
+    When completion is invoked manually, \QC completes the common prefix of the
+    list of suggestions. This is especially useful for classes with several
+    similarly named members. To disable this functionality, deselect the
+    \uicontrol {Autocomplete common prefix} check box.
+
+    Select the \uicontrol {Automatically split strings} check box to split
+    a string to two lines by adding an end quote at the cursor position when
+    you press \key Enter and a start quote at the beginning of the next line,
+    before the rest of the string. In addition, pressing \key {Shift+Enter}
+    inserts an escape character at the cursor position and moves the rest of
+    the string to the next line.
+
+    \section1 Automatically Inserting Matching Characters
+
+    When you have selected code and enter brackets or quotes, the matching
+    closing character is added automatically at the end of the selection.
+
+    By default, the automatically inserted text is highlighted and animated,
+    skipped when you type, and removed when you press \key Backspace.
+
+    \if defined(qtcreator)
+    \sa {Complete CMake code},
+    {Enclose selected code in curly braces, parentheses, or double quotes}, {Nim}
+    \endif
+
+    \sa {Complete code}, {Snippets}
+*/
+
+/*!
+    \page creator-preferences-text-editor-shippets.html
+    \if defined(qtdesignstudio)
+    \previouspage creator-completing-code.html
+    \else
+    \previouspage creator-reference.html
+    \endif
+
+    \ingroup creator-reference-preferences-text-editor
+
+    \title Snippets
+
+    \brief Add, change, and remove snippets in the snippet editor.
+
+    To add, change, and remove snippets in the snippet editor, select
+    \preferences > \uicontrol {Text Editor} > \uicontrol Snippets.
 
     \QC has built-in snippets in the following categories:
 
     \list
-
         \li Text snippets, which can have any text string. For example, code
             comments
-
         \if defined(qtcreator)
         \li C++ code snippets, which specify C++ code constructs
-
         \li CMake code snippets that you can use when editing \c CMakeLists.txt
             files in the CMake editor
         \endif
-
         \li QML code snippets, which specify QML code constructs
-
         \if defined(qtcreator)
         \li Nim code snippets, which specify Nim code constructs
         \endif
-
     \endlist
 
-    \section2 Adding and Editing Snippets
-
-    Select a snippet in the list to edit it in the snippet editor. To add a new
-    snippet, select \uicontrol Add. Specify a trigger and, if the trigger is
-    already in use, an optional variant, which appear in the list of suggestions
-    when you write code.
     \if defined(qtcreator)
-    Also specify a text string or C++ or QML code construct
+    \image qtcreator-edit-code-snippets.png {C++ snippet preferences}
-    in the snippet editor, depending on the snippet category.
+    \caption Built-in C++ code snippets.
-
-    You can use \l{Use Qt Creator variables}{predefined variables} in
-    snippets.
-    \else
-    Also specify a text string or QML code in the snippet editor, depending on
-    the snippet category.
     \endif
 
+    \image qml-snippet-editor.png
+    \caption Built-in QML code snippets.
+
+    \section1 Editing Snippets
+
+    Select a snippet in the list to edit it in the snippet editor.
+
     The snippet editor offers:
 
     \list
@@ -270,7 +300,7 @@
     To discard the changes you made to a built-in snippet, select
     \uicontrol {Revert Built-in}.
 
-    \section2 Removing Snippets
+    \section1 Removing Snippets
 
     The list of suggestions might show several similar built-in snippets for
     different use cases. To make it shorter when you write code, remove the
@@ -281,7 +311,7 @@
     \uicontrol Remove. To restore the removed snippets, select
     \uicontrol {Restore Removed Built-ins}.
 
-    \section2 Resetting Snippets
+    \section1 Resetting Snippets
 
     To remove all added snippets and to restore all removed snippets, select
     \uicontrol {Reset All}.
@@ -290,16 +320,50 @@
     lose all your own snippets.
 
     \if defined(qtcreator)
-    \section1 Completing Nim Code
+    \sa {Complete CMake code}, {Document code}, {Use Qt Creator variables},
-
+    {Nim}
-    You can use the \l{https://nim-lang.org/docs/nimsuggest.html}{Nimsuggest}
-    tool to query \c {.nim} source files and obtain suggestions for code
-    completion.
-
-    To use Nimsuggest, you must install it on the development PC. Then select
-    \preferences > \uicontrol Nim > \uicontrol Tools,
-    and enter the path to the tool executable in the \uicontrol Path field.
-
-    \sa {Document code}, {Use Qt Creator variables}
     \endif
+
+    \sa {Add code snippets to the auto-complete menu}, {Complete code},
+    {Completion}
+*/
+
+/*!
+    \page creator-how-to-add-code-snippets.html
+    \if defined(qtdesignstudio)
+    \previouspage creator-completing-code.html
+    \else
+    \previouspage creator-how-tos.html
+    \endif
+
+    \ingroup creator-how-to-edit
+
+    \title Add code snippets to the auto-complete menu
+
+    To add code or text snippets in the snippet editor:
+
+    \list 1
+        \li Select \preferences > \uicontrol {Text Editor} > \uicontrol Snippets.
+            \image qtcreator-snippet-modifiers.png {Snippets preferences}
+        \li In \uicontrol Group, select the type of snippet to add.
+        \li Select \uicontrol Add.
+        \li Specify a trigger. If the trigger is already in use, add an optional
+            variant. They appear in the list of suggestions when you write code.
+            \if defined(qtcreator)
+            Also specify a text string or C++ or QML code construct
+            in the snippet editor, depending on the snippet category.
+
+            You can use \l{Use Qt Creator variables}{predefined variables} in
+            snippets.
+            \else
+            Also specify a text string or QML code in the snippet editor, depending on
+            the snippet category.
+            \endif
+    \endlist
+
+    \if defined(qtcreator)
+    \sa {Complete CMake code}, {Complete code}, {Use Qt Creator variables},
+    {Nim}
+    \endif
+    \sa {Completion}, {Snippets}
 */

doc/qtcreator/src/editors/creator-editors-options.qdoc

@@ -46,7 +46,7 @@
             {highlighting} or \l{Folding Blocks}{folding} blocks or text
             wrapping in \uicontrol Display.
 
-        \li Add, modify, and remove \l{Editing Code Snippets}{code snippets} in
+        \li Add, modify, and remove \l{Snippets}{code snippets} in
             \uicontrol Snippets.
 
         \if defined(qtcreator)
@@ -54,12 +54,12 @@
             in \uicontrol Macros.
         \endif
 
-        \li Configure \l{Completing Code}{code completion} in \uicontrol Completion.
+        \li Configure \l{Completion}{code completion} in \uicontrol Completion.
 
     \endlist
 
     \if defined(qtcreator)
-    \sa {Specify editor settings}, {Using FakeVim Mode}
+    \sa {Specify editor settings}, {Using FakeVim Mode}, {Completion}, {Snippets}
     \endif
 
 */

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

@@ -46,7 +46,7 @@
             static checks on the QML and JavaScript code in your project to find
             common problems.
 
-        \li \l{Completing Code}
+        \li \l{Complete code}
 
             \QC anticipates what you are going to write and completes code
             and code snippets for elements, properties, and IDs.

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

@@ -23,7 +23,7 @@
 
     \list
 
-        \li \l{Completing Code}{Code completion}
+        \li \l{Complete code}{Code completion}
 
         \li Syntactic and \l{Semantic Highlighting}{semantic highlighting}
 

doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc

@@ -15,7 +15,7 @@
     IDE to offer the following services:
 
     \list
-        \li \l{Completing Code}{Code completion}
+        \li {Complete code}{Code completion}
         \li Sending document formatting requests to the language server to
             automatically format documents using the settings specified in
             \preferences > \uicontrol {Text Editor} > \uicontrol Behavior

doc/qtcreator/src/editors/creator-only/creator-preferences-nim.qdoc

@@ -9,26 +9,38 @@
 
     \title Nim
 
-    \brief Set Nim code style.
+    \brief Set Nim code style and paths to tools.
 
-    To specify settings for the Nim editor (experimental):
+    \section1 Code Style
+
+    To specify preferences for the Nim editor (experimental):
 
     \list 1
         \li Select \preferences > \uicontrol Nim.
         \li In the \uicontrol {Current settings} field, select the settings to
             modify and click \uicontrol Copy.
-            \image qtcreator-options-code-style-nim.png {Nim Code Style preferences}
+            \image qtcreator-preferences-nim-code-style.webp {Nim Code Style preferences}
         \li Give a name to the settings and click \uicontrol OK.
-        \li Click \uicontrol Edit to specify code style settings for the project.
+        \li Specify how to interpret the \key Tab key presses and how to align
-            \image qtcreator-code-style-settings-edit-nim.png {Edit Code Style dialog}
+            continuation lines.
+        \li Select \uicontrol OK to save the settings.
     \endlist
 
-    You can specify how to interpret the \key Tab key presses and how to align
-    continuation lines.
-
     To specify different settings for a particular project, select
     \uicontrol Projects > \uicontrol {Code Style}.
 
-    \sa {Find preferences}, {Indent text or code},
+    \section1 Tools
-    {Specify code style}, {Nimble}
+
+    You can use the \l{https://nim-lang.org/docs/nimsuggest.html}{Nimsuggest}
+    tool to query \c {.nim} source files and obtain suggestions for code
+    completion.
+
+    To use Nimsuggest, you must install it on the development PC and enter the
+    path to the tool executable in the \uicontrol Path field.
+
+    \image qtcreator-preferences-nim-tools.webp
+
+    \sa {Add code snippets to the auto-complete menu}, {Complete code},
+    {Find preferences}, {Indent text or code}, {Specify code style},
+    {Completion}, {Nimble}, {Snippets}
 */

doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

@@ -343,7 +343,7 @@
 
     \image qtcreator-preferences-texteditor-completion.webp "Completion preferences"
 
-    \sa {Completing Code}
+    \sa {Completion}
 */
 
 /*!
@@ -357,23 +357,6 @@
     Press \key {Ctrl+U}.
 */
 
-/*!
-    \page creator-how-to-add-code-snippets.html
-    \previouspage creator-how-tos.html
-
-    \ingroup creator-how-to-edit
-
-    \title Add code snippets to the auto-complete menu
-
-    Add, modify, and remove snippets in the snippet editor.
-    To open the editor, select \preferences > \uicontrol {Text Editor} >
-    \uicontrol Snippets.
-
-    \image qtcreator-snippet-modifiers.png "Snippets preferences"
-
-    For more information, see \l {Adding and Editing Snippets}.
-*/
-
 /*!
     \page creator-how-to-write-notes.html
     \previouspage creator-how-tos.html

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

@@ -123,7 +123,7 @@
     To open the snippet editor, select \preferences >
     \uicontrol {Text Editor} > \uicontrol Snippets.
 
-    For more information, see \l{Editing Code Snippets}.
+    For more information, see \l{Snippets}.
 
     \section1 Configuring Version Control Systems
 

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

@@ -33,6 +33,8 @@
 
     \section1 Preferences
 
+    Set prefecerences that apply globally to all projects.
+
     \annotatedlist creator-reference-preferences
 
     \section2 Analyzer
@@ -45,6 +47,8 @@
 
     \section2 Text Editor
 
+    Configure the text editor to suit your needs.
+
     \annotatedlist creator-reference-preferences-text-editor
 
     \section1 UI Design

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -32,7 +32,6 @@
                 \li \l{Working in Edit Mode}
                 \li \l{Semantic Highlighting}
                 \li \l{Checking Code Syntax}
-                \li \l{Completing Code}
                 \li \l{Using Qt Quick Toolbars}
                 \li \l{Pasting and Fetching Code Snippets}
                 \li \l{Using Text Editing Macros}

doc/qtcreator/src/qtquick/creator-only/qtquick-app-tutorial.qdoc

@@ -76,7 +76,7 @@
     \printuntil color
 
     When you start typing the QML type name, \QC suggests available types
-    and properties to \l{Completing Code}{complete the code}.
+    and properties to \l{Complete code}{complete the code}.
 
     Select the light bulb icon \inlineimage icons/refactormarker.png
     next to the type name to open the \l{Editing Rectangles}

doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc

@@ -203,7 +203,6 @@
                             \list
                                 \li \l{Semantic Highlighting}
                                 \li \l{Checking Code Syntax}
-                                \li \l{Completing Code}
                                 \li \l{Indent text or code}
                                 \li \l{Behavior}
                                 \li \l{Qt Quick Code Style}

doc/qtdesignstudio/src/views/qtquick-states.qdoc

@@ -82,7 +82,7 @@
     \image qtquick-states-binding-editor.png "Binding Editor in States view"
 
     When you compose the expressions in \uicontrol {Binding Editor}, the
-    \l{Completing Code}{code completion} feature lists the components and
+    \l{Complete code}{code completion} feature lists the components and
     their properties you can use in the expressions.
 
     \include creator-logical-operators.qdocinc logical operators

doc/qtdesignstudio/src/views/qtquick-text-editor.qdoc

@@ -26,7 +26,7 @@
     \list
         \li \l{Semantic Highlighting}
         \li \l{Checking Code Syntax}
-        \li \l{Completing Code}
+        \li \l{Complete code}
         \li \l{Indent text or code}
         \li \l{Using Qt Quick Toolbars}
     \endlist