Doc: Address documentation issues from Qt 6.7 CMake API review

Task-number: QTBUG-122671
Change-Id: Ic274597ff51ba297aa29f83ea0c0a4c893e0533b
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit dc1d3497f1644ce5e6aeb6ae74f34e8e7eaf434b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 258 insertions, 41 deletions

diff --git a/src/linguist/linguist/doc/cmake-macros.qdoc b/src/linguist/linguist/doc/cmake-macros.qdoc
index 1e3d5dd15..e34064fb5 100644
--- a/src/linguist/linguist/doc/cmake-macros.qdoc
+++ b/src/linguist/linguist/doc/cmake-macros.qdoc
@@ -235,6 +235,17 @@ Add the targets \c{myapp_lupdate} and \c{update_translations} for updating the
 \c{.ts} file of an application \c{myapp}.
 
 \snippet cmake-macros/examples.cmake qt_add_lupdate
+
+You can specify the name of the created target by passing the \c LUPDATE_TARGET
+argument:
+
+\badcode
+qt_add_lupdate(
+    LUPDATE_TARGET update_application_translations
+    TS_FILES myapp_de.ts
+    PLURALS_TS_FILE myapp_en.ts
+)
+\endcode
 */
 
 /*!
@@ -252,6 +263,7 @@ Add the targets \c{myapp_lupdate} and \c{update_translations} for updating the
 
 \section1 Synopsis
 
+Since 6.7:
 \badcode
 qt_add_lrelease(TS_FILES file1.ts [file2.ts ...]
                 [LRELEASE_TARGET target-name]
@@ -261,6 +273,15 @@ qt_add_lrelease(TS_FILES file1.ts [file2.ts ...]
                 [OPTIONS ...])
 \endcode
 
+Since 6.2 (deprecated):
+\badcode
+qt_add_lrelease(target TS_FILES file1.ts [file2.ts ...]
+                [NO_TARGET_DEPENDENCY]
+                [NO_GLOBAL_TARGET]
+                [QM_FILES_OUTPUT_VARIABLE variable-name]
+                [OPTIONS ...])
+\endcode
+
 \versionlessCMakeCommandsNote qt6_add_lrelease()
 
 \warning Calling \c qt_add_lrelease in a directory scope different than the
@@ -331,11 +352,30 @@ is still possible but deprecated.
 
 \section1 Examples
 
-Add the targets \c{myapp_lrelease} and \c{update_translations} for updating the
-\c{.ts} file of an application \c{myapp}. Also, install the generated \c{.qm}
-files.
+Add the targets \c{myapp_lrelease} and \c{release_translations} for transforming
+the given \c{.ts} files into \c{.qm} files. Also, install the generated \c{.qm}
+files. The target \c{myapp_lrelease} is built by default.
+
+\badcode
+project(myapp)
+...
+qt_add_lrelease(
+    TS_FILES myapp_de.ts myapp_fr.ts
+    QM_FILES_OUTPUT_VARIABLE qm_files
+)
+install(FILES ${qm_files} DESTINATION "translations")
+\endcode
+
+You can specify the name of the created target by passing the \c LRELEASE_TARGET
+argument:
 
-\snippet cmake-macros/examples.cmake qt_add_lrelease_install
+\badcode
+qt_add_lrelease(
+    LRELEASE_TARGET create_myapp_qm_files
+    TS_FILES myapp_de.ts myapp_fr.ts
+    QM_FILES_OUTPUT_VARIABLE qm_files
+)
+\endcode
 */
 
 /*!
@@ -353,6 +393,7 @@ files.
 
 \section1 Synopsis
 
+Since Qt 6.7:
 \badcode
 qt_add_translations([target]
                     [TARGETS target1 [target2...]]
@@ -374,6 +415,18 @@ qt_add_translations([target]
                     [IMMEDIATE_CALL])
 \endcode
 
+Since Qt 6.2 (deprecated):
+\badcode
+qt_add_translations(target TS_FILES file1.ts [file2.ts ...]
+                    [RESOURCE_PREFIX prefix]
+                    [OUTPUT_TARGETS variable-name]
+                    [QM_FILES_OUTPUT_VARIABLE variable-name]
+                    [SOURCES source1.cpp [sources2.cpp ...]]
+                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
+                    [LUPDATE_OPTIONS ...]
+                    [LRELEASE_OPTIONS ...])
+\endcode
+
 \versionlessCMakeCommandsNote qt6_add_translations()
 
 \warning Calling \c qt_add_translations in a directory scope different than the
@@ -416,7 +469,8 @@ details.
 \section1 Automatic Determination of .ts File Paths
 
 The paths of the \c{.ts} files that are used as input for \c qt_add_translations
-can be automatically determined if \l{QT_I18N_TRANSLATED_LANGUAGES} has been set.
+can be automatically determined if \l{QT_I18N_TRANSLATED_LANGUAGES} has been
+set. This variable can be conveniently set with \l qt_standard_project_setup.
 
 The following project setup is usually enough:
 
@@ -520,24 +574,112 @@ anymore.
 
 \section1 Examples
 
-Add a German translation to a target \c{super_calc} using
+Add a German and a French translation to the target \c{frogger} using
 \c{qt_add_translations}:
 
 \snippet cmake-macros/examples.cmake qt_add_translations_default
 
-This is roughly equivalent to the following:
+This will create the \c{.ts} files \c{frogger_de.ts} and \c{frogger_fr.ts} in
+the source directory. \l lupdate sees the source files of all targets that are
+eligible for translation, according to the rules of \l
+qt_collect_translation_source_targets.
+
+The \c{.qm} files that are created from the \c{.ts} files
+are embedded in the \c frogger_game target under the resource prefix \c{"i18n"}.
+
+The \c qt_add_translations call in the above example is roughly equivalent to
+the following:
 
 \snippet cmake-macros/examples.cmake qt_lupdate_lrelease
 
-Add a Norwegian translation to \c{frogger_game} and \c{frogger_level_editor}
-with a custom resource prefix:
+\section2 Excluding directories, targets, and sources
+
+You can exclude targets and directories from the automatic collection of source
+targets. The following excludes the target \c helper_lib and everything under
+the \c tests directory. See the \l{directory property
+QT_EXCLUDE_FROM_TRANSLATION} and the \l{target property
+QT_EXCLUDE_FROM_TRANSLATION}.
+
+\badcode
+# <project_root>/CMakeLists.txt
+qt_add_translations(frogger_game)
+\endcode
+
+\badcode
+# <project_root>/src/helper_lib/CMakeLists.txt
+qt_add_library(helper_lib STATIC helpers.cpp)
+set_property(TARGET helper_lib PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)
+\endcode
+
+\badcode
+# <project_root>/tests/CMakeLists.txt
+add_subdirectory(behavior_tests)
+add_subdirectory(physics_tests)
+set_directory_properties(PROPERTIES QT_EXCLUDE_FROM_TRANSLATION ON)
+\endcode
+
+In the following example, we exclude source files that are part of the \c
+frogger_game target using the \l QT_EXCLUDE_SOURCES_FROM_TRANSLATION target
+property:
+
+\badcode
+qt_add_executable(frogger_game
+    main.cpp
+    3rdparty/jumpsim.cpp
+    3rdparty/frogmath.cpp
+)
+set_property(TARGET frogger_game
+    PROPERTY QT_EXCLUDE_SOURCES_FROM_TRANSLATION "3rdparty/*"
+)
+\endcode
+
+\section2 Explicit specification of source targets
+
+If you don't want to use the automatic collection of source targets you can
+specify the source targets explicitly:
+
+\snippet cmake-macros/examples.cmake qt_add_translations_explicit_source_targets
+
+\section2 Custom resource prefix
+
+Now, let's embed the \c{.qm} files in \c frogger_game and \c
+frogger_level_editor and set a custom resource prefix.
 
 \snippet cmake-macros/examples.cmake qt_add_translations_resource_prefix
 
-Add a Finnish translation to \c{business_logic}, and install the generated
-\c{.qm} files:
+\section2 Installing .qm files
+
+Instead of embedding the \c{.qm} files we can install them as regular files:
 
 \snippet cmake-macros/examples.cmake qt_add_translations_install
+
+\section2 Influencing the names of the .ts files
+
+Place the \c{.ts} files in a \c translations directory and change the base name
+to \c frogger_i18n:
+
+\badcode
+qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
+...
+qt_add_translations(frogger
+    TS_BASE_NAME froggo
+    TS_FILE_DIR translations
+)
+\endcode
+
+This creates the following files
+\list
+\li \c translations/froggo_de.ts
+\li \c translations/froggo_fr.ts
+\endlist
+
+You can also specify the paths explicitly:
+\badcode
+qt_add_translations(frogger
+    TS_FILES translations/froggo_de.ts translations/froggo_fr.ts
+)
+\endcode
+
 */
 
 /*!
@@ -583,9 +725,10 @@ property QT_EXCLUDE_FROM_TRANSLATION}.
 
 \section1 When to call this command
 
-The \c qt_collect_translation_source_targets command reads the \c
-BUILDSYSTEM_TARGETS directory properties. As a consequence, it only collects
-targets that already have been created. Targets that are created after \c
+The \c qt_collect_translation_source_targets command reads the
+\l{https://cmake.org/cmake/help/latest/prop_dir/BUILDSYSTEM_TARGETS.html}{BUILDSYSTEM_TARGETS}
+directory properties. As a consequence, it only collects targets that already
+have been created. Targets that are created after \c
 qt_collect_translation_source_targets has been called are not collected.
 
 To collect all targets of the build system, call \c
@@ -599,4 +742,12 @@ Use the result of \c qt_collect_translation_source_targets as input for \c
 qt_add_lupdate.
 
 \snippet cmake-macros/examples.cmake qt_collect_translation_source_targets
+
+With CMake 3.19 and above, you can collect the source targets at the end of the
+directory scope. This way, \c qt_collect_translation_source_targets can be
+called before all targets have been defined. However, you need to exclude the
+tests by setting the directory property \l{directory property
+QT_EXCLUDE_FROM_TRANSLATION}{QT_EXCLUDE_FROM_TRANSLATION} to \c{ON}.
+
+\snippet cmake-macros/examples.cmake qt_collect_translation_source_targets_deferred
 */
diff --git a/src/linguist/linguist/doc/cmake-properties.qdoc b/src/linguist/linguist/doc/cmake-properties.qdoc
index f85e90a5d..ee518f7a7 100644
--- a/src/linguist/linguist/doc/cmake-properties.qdoc
+++ b/src/linguist/linguist/doc/cmake-properties.qdoc
@@ -29,8 +29,30 @@ its subdirectories from translation. The command
 \l{qt6_collect_translation_source_targets}{qt_collect_translation_source_targets}
 will skip such targets.
 
-To exclude a single target, use the \l{target property
-QT_EXCLUDE_FROM_TRANSLATION}.
+To exclude a single target, use the target property \l{target property
+QT_EXCLUDE_FROM_TRANSLATION}{QT_EXCLUDE_FROM_TRANSLATION}.
+
+\section1 Examples
+
+In the following example, translatable strings will not be extracted from
+targets that are defined in the \c tests directory.
+
+\badcode
+add_subdirectory(app)
+add_subdirectory(tests)
+set_property(DIRECTORY tests PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)
+qt_add_translations(myapp)
+\endcode
+
+Alternatively, you can set the directory property in the \c{CMakeLists.txt} of
+the \c tests subdirectory.
+
+\badcode
+# tests/CMakeLists.txt
+qt_add_executable(...)
+add_test(...)
+set_directory_properties(PROPERTIES QT_EXCLUDE_FROM_TRANSLATION ON)
+\endcode
 
 \sa QT_EXCLUDE_SOURCES_FROM_TRANSLATION
 */
@@ -63,8 +85,20 @@ Set this target property to \c ON to exclude it from translation. The command
 \l{qt6_collect_translation_source_targets}{qt_collect_translation_source_targets}
 will skip such targets.
 
-To exclude all targets under a subdirectory, use the \l{directory property
-QT_EXCLUDE_FROM_TRANSLATION}.
+To exclude all targets under a subdirectory, use the directory property
+\l{directory property QT_EXCLUDE_FROM_TRANSLATION}{QT_EXCLUDE_FROM_TRANSLATION}.
+
+\section1 Examples
+
+In the following example, translatable strings will not be extracted from the \c
+mytest target.
+
+\badcode
+qt_add_executable(myapp main.cpp)
+qt_add_executable(mytest test.cpp)
+set_property(TARGET mytest PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)
+qt_add_translations(myapp)
+\endcode
 
 \sa QT_EXCLUDE_SOURCES_FROM_TRANSLATION
 */
@@ -82,11 +116,16 @@ QT_EXCLUDE_FROM_TRANSLATION}.
 \cmakepropertysince 6.7
 
 This target property specifies a list of source file paths that are excluded
-from translation. The paths may be absolute or relative to
-\c{CMAKE_CURRENT_SOURCE_DIR}. The paths may contain wildcards.
+from translation. Source files that match the patterns in this exclusion list
+are ignored by \c{lupdate}.
+
+The paths may be absolute or relative to \c{CMAKE_CURRENT_SOURCE_DIR}. The paths
+may contain wildcards in a format that is accepted by
+\l{QRegularExpression::wildcardToRegularExpression}.
 
 \snippet cmake-macros/examples.cmake exclude sources from i18n
 
+\sa qt_add_lupdate
 \sa {target property QT_EXCLUDE_FROM_TRANSLATION}
 \sa {directory property QT_EXCLUDE_FROM_TRANSLATION}
 */
diff --git a/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
index 95f87c828..4c52d745b 100644
--- a/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
+++ b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
@@ -33,59 +33,86 @@ set_source_files_properties(app_en.ts app_de.ts
 
 #! [qt_add_lupdate]
 qt_add_lupdate(
+    SOURCE_TARGETS myapp
     TS_FILES myapp_de.ts
     PLURALS_TS_FILE myapp_en.ts
 )
 #! [qt_add_lupdate]
 
-#! [qt_add_lrelease_install]
-qt_add_lrelease(myapp
-    TS_FILES myapp_de.ts
-    QM_FILES_OUTPUT_VARIABLE qm_files)
-install(FILES ${qm_files} DESTINATION "translations")
-#! [qt_add_lrelease_install]
-
 #! [qt_add_translations_default]
-qt_add_translations(super_calc TS_FILES super_calc_de.ts)
+cmake_minimum_required(VERSION 3.28)
+project(frogger)
+find_package(Qt6 COMPONENTS OpenGLWidgets)
+qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)
+
+# The CMake files in the 'src' subdirectory create
+# the targets 'frogger_game' and 'frogger_level_editor'.
+add_subdirectory(src)
+
+# Add translations to the 'frogger_game' target.
+qt_add_translations(frogger_game)
 #! [qt_add_translations_default]
 
 #! [qt_lupdate_lrelease]
 qt_collect_translation_source_targets(i18n_targets)
 qt_add_lupdate(
-    TARGETS ${i18n_targets}
-    TS_FILES super_calc_de.ts)
+    SOURCE_TARGETS ${i18n_targets}
+    TS_FILES frogger_de.ts frogger_fr.ts)
 qt_add_lrelease(
-    TS_FILES super_calc_de.ts
+    TS_FILES frogger_de.ts frogger_fr.ts
     QM_FILES_OUTPUT_VARIABLE qm_files)
-qt_add_resources(super_calc "translations"
+qt_add_resources(frogger_game "translations"
     PREFIX "/i18n"
     BASE "${CMAKE_CURRENT_BINARY_DIR}"
-    FILES "${qm_files}")
+    FILES "${qm_files}"
+)
 #! [qt_lupdate_lrelease]
 
+#! [qt_add_translations_explicit_source_targets]
+qt_add_translations(frogger_game
+    SOURCE_TARGETS frogger_game
+)
+#! [qt_add_translations_explicit_source_targets]
+
 #! [qt_add_translations_resource_prefix]
 qt_add_translations(
     TARGETS frogger_game frogger_level_editor
-    TS_FILES frogger_game_no.ts
-    RESOURCE_PREFIX "/translations")
+    RESOURCE_PREFIX "/translations"
+)
 #! [qt_add_translations_resource_prefix]
 
 #! [qt_add_translations_install]
-qt_add_translations(business_logic
-    TS_FILES myapp_fi.ts
-    QM_FILES_OUTPUT_VARIABLE qm_files)
+qt_add_translations(
+    TARGETS frogger_game frogger_level_editor
+    QM_FILES_OUTPUT_VARIABLE qm_files
+)
 install(FILES ${qm_files} DESTINATION "translations")
 #! [qt_add_translations_install]
 
 #! [qt_collect_translation_source_targets]
-add_subdirectory(src)          # the actual application is defined here
+add_subdirectory(src)         # The actual application is defined here.
 
+# All targets that have been defined up to this point will be in i18n_targets.
 qt_collect_translation_source_targets(i18n_targets)
-qt_add_lupdate(TARGETS ${i18n_targets})
+qt_add_lupdate(SOURCE_TARGETS ${i18n_targets})
 
-add_subdirectory(tests)        # unit tests - we don't want to translate those
+# No targets from this directory are in i18n_targets.
+add_subdirectory(tests)       # Unit tests - we don't want to translate those.
 #! [qt_collect_translation_source_targets]
 
+#! [qt_collect_translation_source_targets_deferred]
+function(set_up_translations)
+    qt_collect_translation_source_targets(i18n_targets)
+    qt_add_lupdate(SOURCE_TARGETS ${i18n_targets})
+endfunction()
+
+cmake_language(DEFER CALL set_up_translations)
+
+add_subdirectory(src)         # The actual application is defined here.
+add_subdirectory(tests)       # Unit tests - we don't want to translate those.
+set_property(DIRECTORY tests PROPERTY QT_EXCLUDE_FROM_TRANSLATION ON)
+#! [qt_collect_translation_source_targets_deferred]
+
 #! [exclude sources from i18n]
 qt_add_executable(myapp
     main.cpp