Doc: Add global \versionlessCMakeCommandsNote qdoc macro

When documenting a CMake command, document the unversioned command
'qt_foo' and use '\versionlessCMakeCommandNote qt6_foo' to refer to the
versioned command.  This avoids duplicating the command signature.

Use the new macro where applicable.

Pick-to: 6.2
Task-number: QTBUG-95796
Change-Id: I2e4180fbda0b89acf3d8c036459f591eb2f46475
Reviewed-by: Craig Scott <craig.scott@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

4 files changed, 36 insertions, 60 deletions

diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index 93d5749354..0efbf05dfb 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -71,3 +71,5 @@ macro.preliminarycmakeproperty = "\\note This property is in technology preview
 macro.cmakecommandandroidonly  = "\\note This command should only be called if targeting the Android platform."
 macro.cmakepropertyandroidonly = "\\note This property is used only if targeting the Android platform."
 macro.cmakevariableandroidonly = "\\note This variable is used only if targeting the Android platform."
+
+macro.versionlessCMakeCommandsNote = "If \\l{Versionless commands}{versionless commands} are disabled, use \\c{\1} instead. It supports the same set of arguments as this command."
diff --git a/src/corelib/doc/src/cmake-macros.qdoc b/src/corelib/doc/src/cmake-macros.qdoc
index 9b486712f7..02d33dc445 100644
--- a/src/corelib/doc/src/cmake-macros.qdoc
+++ b/src/corelib/doc/src/cmake-macros.qdoc
@@ -42,12 +42,10 @@ qt_wrap_cpp(<VAR> src_file1 [src_file2 ...]
             [OPTIONS ...]
             [DEPENDS ...])
 
-qt6_wrap_cpp(<VAR> src_file1 [src_file2 ...]
-             [TARGET target]
-             [OPTIONS ...]
-             [DEPENDS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_wrap_cpp()
+
 \section1 Description
 
 Creates rules for calling the \l{moc}{Meta-Object Compiler (moc)} on the given
@@ -90,11 +88,10 @@ Q_PLUGIN_METADATA() macro.
 \badcode
 qt_add_resources(<VAR> file1.qrc [file2.qrc ...]
                   [OPTIONS ...])
-
-qt6_add_resources(<VAR> file1.qrc [file2.qrc ...]
-                  [OPTIONS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_resources()
+
 Since 6.0:
 
 \badcode
@@ -103,14 +100,10 @@ qt_add_resources(<TARGET> <RESOURCE_NAME>
                   [LANG <LANGUAGE>]
                   [BASE <PATH>]
                   [FILES ...] [OPTIONS ...])
-
-qt6_add_resources(<TARGET> <RESOURCE_NAME>
-                  [PREFIX <PATH>]
-                  [LANG <LANGUAGE>]
-                  [BASE <PATH>]
-                  [FILES ...] [OPTIONS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_resources()
+
 \section1 Description
 
 To add resources, you can pass either a variable name or a target as the first
@@ -182,11 +175,10 @@ different static libraries conflict in the consuming target.
 \badcode
 qt_add_big_resources(<VAR> file1.qrc [file2.qrc ...]
                      [OPTIONS ...])
-
-qt6_add_big_resources(<VAR> file1.qrc [file2.qrc ...]
-                     [OPTIONS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_big_resources()
+
 \section1 Description
 
 Creates compiled object files from Qt resource files using the
@@ -225,12 +217,10 @@ You can find possible options in the \l{rcc}{rcc documentation}.
 qt_add_binary_resources(target file1.qrc [file2.qrc ...]
                         [DESTINATION ...]
                         [OPTIONS ...])
-
-qt6_add_binary_resources(target file1.qrc [file2.qrc ...]
-                        [DESTINATION ...]
-                        [OPTIONS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_binary_resources()
+
 \section1 Description
 
 Adds a custom \c target that compiles Qt resource files into a binary \c{.rcc}
@@ -263,11 +253,10 @@ You can find possible options in the \l{rcc}{rcc documentation}.
 \badcode
 qt_generate_moc(src_file dest_file
                 [TARGET target])
-
-qt6_generate_moc(src_file dest_file
-                [TARGET target])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_generate_moc()
+
 \section1 Description
 
 Creates a rule to call the \l{moc}{Meta-Object Compiler (moc)} on \c src_file
@@ -306,14 +295,10 @@ qt_import_plugins(target
                   [EXCLUDE plugin ...]
                   [INCLUDE_BY_TYPE plugin_type plugin ...]
                   [EXCLUDE_BY_TYPE plugin_type])
-
-qt6_import_plugins(target
-                  [INCLUDE plugin ...]
-                  [EXCLUDE plugin ...]
-                  [INCLUDE_BY_TYPE plugin_type plugin ...]
-                  [EXCLUDE_BY_TYPE plugin_type])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_import_plugins()
+
 \section1 Description
 
 Specifies a custom set of plugins to import. The optional arguments:
@@ -378,13 +363,10 @@ qt_add_executable(target
                   [WIN32] [MACOSX_BUNDLE]
                   [MANUAL_FINALIZATION]
                   sources...)
-
-qt6_add_executable(target
-                   [WIN32] [MACOSX_BUNDLE]
-                   [MANUAL_FINALIZATION]
-                   sources...)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_executable()
+
 \section1 Description
 
 This command performs the following tasks:
@@ -471,10 +453,10 @@ for finalizing the target by adding the \c{MANUAL_FINALIZATION} keyword.
 
 \badcode
 qt_finalize_target(target)
-
-qt6_finalize_target(target)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_finalize_target()
+
 \section1 Description
 
 After a target is created, further processing or \e{finalization} steps are
@@ -513,10 +495,10 @@ in the documentation of that command.
 
 \badcode
 qt_android_apply_arch_suffix(target)
-
-qt6_android_apply_arch_suffix(target)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_android_apply_arch_suffix()
+
 \section1 Description
 
 The CMake \c{SUFFIX} target property controls the suffix used on the file name
@@ -543,10 +525,10 @@ overwriting each other.
 
 \badcode
 qt_android_generate_deployment_settings(target)
-
-qt6_android_generate_deployment_settings(target)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_android_generate_deployment_settings()
+
 \section1 Description
 
 The \c{androiddeployqt} tool expects a deployment settings file as input. This
@@ -620,10 +602,10 @@ contain the location of the generated deployment settings file.
 
 \badcode
 qt_android_add_apk_target(target)
-
-qt6_android_add_apk_target(target)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_android_add_apk_target()
+
 \section1 Description
 
 The \c{<target>_make_apk} custom target created by this command takes an Android
diff --git a/src/dbus/doc/src/qtdbus-cmake.qdoc b/src/dbus/doc/src/qtdbus-cmake.qdoc
index 0c8a253e19..f4432fb741 100644
--- a/src/dbus/doc/src/qtdbus-cmake.qdoc
+++ b/src/dbus/doc/src/qtdbus-cmake.qdoc
@@ -39,10 +39,10 @@ description file.
 
 \badcode
 qt_add_dbus_interface(<VAR> dbus_spec basename)
-
-qt6_add_dbus_interface(<VAR> dbus_spec basename)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_dbus_interface()
+
 \section1 Description
 
 Generates C++ sources implementing an interface for a D-Bus interface description
@@ -103,10 +103,10 @@ description files.
 
 \badcode
 qt_add_dbus_interfaces(<VAR> dbus_spec1 [dbus_spec2 ...])
-
-qt6_add_dbus_interfaces(<VAR> dbus_spec1 [dbus_spec2 ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_dbus_interfaces()
+
 \section1 Description
 
 Generates C++ sources implementing D-Bus interfaces defined in \c{dbus_spec1},
@@ -162,13 +162,10 @@ qt_generate_dbus_interface(header
     [customName]
     [OPTIONS options]
 )
-
-qt6_generate_dbus_interface(header
-    [customName]
-    [OPTIONS options]
-)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_generate_dbus_interface()
+
 \section1 Description
 
 Parses the C++ source or header file containing a QObject-derived class
@@ -201,14 +198,10 @@ qt_add_dbus_adaptor(<VAR> dbus_spec header
     [basename]
     [classname]
 )
-
-qt6_add_dbus_adaptor(<VAR> dbus_spec header
-    [parent_class]
-    [basename]
-    [classname]
-)
 \endcode
 
+\versionlessCMakeCommandsNote qt6_add_dbus_adaptor()
+
 \section1 Description
 
 Generates a C++ header file implementing an adaptor for a D-Bus interface
diff --git a/src/widgets/doc/src/cmake-macros.qdoc b/src/widgets/doc/src/cmake-macros.qdoc
index 108d63a7dd..c7a914f42d 100644
--- a/src/widgets/doc/src/cmake-macros.qdoc
+++ b/src/widgets/doc/src/cmake-macros.qdoc
@@ -39,11 +39,10 @@
 \badcode
 qt_wrap_ui(<VAR> ui_file1 [ui_file2 ...]
            [OPTIONS ...])
-
-qt6_wrap_ui(<VAR> ui_file1 [ui_file2 ...]
-           [OPTIONS ...])
 \endcode
 
+\versionlessCMakeCommandsNote qt6_wrap_ui()
+
 \section1 Description
 
 Creates rules for calling the \l{uic}{User Interface Compiler (uic)} on the given