From 23125b3f018f0dd27c761d2ba0e0dfca3d60b4f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20K=C3=B6hne?= Date: Fri, 24 Sep 2021 07:48:23 +0200 Subject: [PATCH] Doc: Add summary to CMake commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For normal \page elements, \brief is just showing in the \generatelist or \annotatedlist commands. Make sure the description is also visible in the actual CMake command/variable/property page by defining a \summary macro. Pick-to: 6.2 Change-Id: I12bc854d547059a2f6309a5922bb0b2a36d4e41c Reviewed-by: Craig Scott Reviewed-by: Topi Reiniö --- doc/global/macros.qdocconf | 3 +++ .../doc/src/cmake/cmake-properties.qdoc | 24 +++++++++---------- .../doc/src/cmake/cmake-variables.qdoc | 12 +++++----- .../doc/src/cmake/qt_add_big_resources.qdoc | 2 +- .../src/cmake/qt_add_binary_resources.qdoc | 2 +- .../doc/src/cmake/qt_add_executable.qdoc | 2 +- src/corelib/doc/src/cmake/qt_add_library.qdoc | 2 +- src/corelib/doc/src/cmake/qt_add_plugin.qdoc | 2 +- .../doc/src/cmake/qt_add_resources.qdoc | 2 +- .../src/cmake/qt_allow_non_utf8_sources.qdoc | 2 +- .../src/cmake/qt_android_add_apk_target.qdoc | 2 +- .../cmake/qt_android_apply_arch_suffix.qdoc | 2 +- ..._android_generate_deployment_settings.qdoc | 2 +- .../src/cmake/qt_disable_unicode_defines.qdoc | 2 +- .../doc/src/cmake/qt_extract_metatypes.qdoc | 2 +- .../doc/src/cmake/qt_finalize_target.qdoc | 2 +- .../doc/src/cmake/qt_generate_moc.qdoc | 2 +- .../doc/src/cmake/qt_import_plugins.qdoc | 2 +- .../doc/src/cmake/qt_set_finalizer_mode.qdoc | 2 +- src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc | 2 +- src/dbus/doc/src/qtdbus-cmake.qdoc | 10 ++++---- src/widgets/doc/src/cmake-macros.qdoc | 2 +- 22 files changed, 44 insertions(+), 41 deletions(-) diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf index 0efbf05dfb..5faa7ce9f3 100644 --- a/doc/global/macros.qdocconf +++ b/doc/global/macros.qdocconf @@ -46,6 +46,9 @@ macro.endfloat.HTML = "" macro.clearfloat.HTML = "
" macro.emptyspan.HTML = "" +# Use like \brief, but replicates sentence also as text +macro.summary = "\\brief \1\n\n\1\n" + # Expands to the minor version based on the QT_VER environment variable macro.QtMinorVersion = "$QT_VER" macro.QtMinorVersion.match = "\\d+\\.(\\d+)" diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc index 8134209636..b5db780fde 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -63,7 +63,7 @@ is listed before its dependencies, it will fail to load on some devices. \title QT_ANDROID_EXTRA_LIBS \target cmake-target-property-QT_ANDROID_EXTRA_LIBS -\brief Extra libraries to deploy with the target. +\summary Extra libraries to deploy with the target. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -84,7 +84,7 @@ to enable OpenSSL in your application. For more information, see \title QT_ANDROID_EXTRA_PLUGINS \target cmake-target-property-QT_ANDROID_EXTRA_PLUGINS -\brief Extra Qt plugins to deploy with the target. +\summary Extra Qt plugins to deploy with the target. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -114,7 +114,7 @@ mangling is applied to the plugin library. \title QT_ANDROID_MIN_SDK_VERSION \target cmake-target-property-QT_ANDROID_MIN_SDK_VERSION -\brief Minimum Android SDK version. +\summary Minimum Android SDK version. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -132,7 +132,7 @@ Specifies the minimum Android API level for the target. \title QT_ANDROID_PACKAGE_SOURCE_DIR \target cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR -\brief Path to a custom Android package template. +\summary Path to a custom Android package template. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -164,7 +164,7 @@ then place this directly into the directory specified by this variable. \title QT_ANDROID_TARGET_SDK_VERSION \target cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION -\brief Android target SDK version. +\summary Android target SDK version. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -182,7 +182,7 @@ Specifies the target Android API level for the target. \title QT_ANDROID_VERSION_CODE \target cmake-target-property-QT_ANDROID_VERSION_CODE -\brief Internal Android app version. +\summary Internal Android app version. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -203,7 +203,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. \title QT_ANDROID_VERSION_NAME \target cmake-target-property-QT_ANDROID_VERSION_NAME -\brief Human-readable Android app version. +\summary Human-readable Android app version. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -224,7 +224,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. \title QT_QML_ROOT_PATH \target cmake-target-property-QT_QML_ROOT_PATH -\brief Overrides the location of the application's qml directory. +\summary Overrides the location of the application's qml directory. \preliminarycmakeproperty @@ -244,7 +244,7 @@ will be used instead. \title QT_QML_IMPORT_PATH \target cmake-target-property-QT_QML_IMPORT_PATH -\brief Specifies a list of directories to search for QML imports. +\summary Specifies a list of directories to search for QML imports. \preliminarycmakeproperty @@ -265,7 +265,7 @@ For application-specific QML imports, use \title QT_ANDROID_DEPLOYMENT_SETTINGS_FILE \target cmake-target-property-QT_ANDROID_DEPLOYMENT_SETTINGS_FILE -\brief Specifies the location of a target's generated deployment settings file. +\summary Specifies the location of a target's generated deployment settings file. \preliminarycmakeproperty \cmakepropertyandroidonly @@ -284,7 +284,7 @@ and overwritten by that command. \title qt_no_entrypoint \target cmake-target-property-qt_no_entrypoint -\brief Specifies to inhibit linking against Qt's entrypoint lib. +\summary Specifies to inhibit linking against Qt's entrypoint lib. \preliminarycmakeproperty @@ -302,7 +302,7 @@ On targets that must provide their own entry point, set the property \c qt_no_en \title QT_RESOURCE_PREFIX \target cmake-target-property-QT_RESOURCE_PREFIX -\brief Specifies the default Qt resource prefix. +\summary Specifies the default Qt resource prefix. \preliminarycmakeproperty diff --git a/src/corelib/doc/src/cmake/cmake-variables.qdoc b/src/corelib/doc/src/cmake/cmake-variables.qdoc index bae057c23e..52a25956f7 100644 --- a/src/corelib/doc/src/cmake/cmake-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-variables.qdoc @@ -33,7 +33,7 @@ \title ANDROID_NDK_HOST_SYSTEM_NAME \target cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME -\brief Android-specific architecture of the host system. +\summary Android-specific architecture of the host system. \preliminarycmakevariable \cmakevariableandroidonly @@ -52,7 +52,7 @@ part of the deployment settings for a target. \title ANDROID_SDK_ROOT \target cmake-variable-ANDROID_SDK_ROOT -\brief Location of the Android SDK. +\summary Location of the Android SDK. \preliminarycmakevariable \cmakevariableandroidonly @@ -71,7 +71,7 @@ It is written out as part of the deployment settings for a target. \title QT_ANDROID_APPLICATION_ARGUMENTS \target cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS -\brief List of arguments to pass to Android applications. +\summary List of arguments to pass to Android applications. \preliminarycmakevariable \cmakevariableandroidonly @@ -90,7 +90,7 @@ out as part of the deployment settings for a target. \title QT_HOST_PATH \target cmake-variable-QT_HOST_PATH -\brief Location of the host Qt installation when cross-compiling. +\summary Location of the host Qt installation when cross-compiling. \preliminarycmakevariable @@ -107,7 +107,7 @@ platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, \title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID \target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID -\brief Disables providing a fallback team ID during target finalization on iOS. +\summary Disables providing a fallback team ID during target finalization on iOS. When finalizing an executable target on iOS, \l{qt6_finalize_target}{qt_finalize_target()} will populate the target's @@ -123,7 +123,7 @@ Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this. \title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER \target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER -\brief Disables providing a fallback app bundle ID during target finalization on iOS. +\summary Disables providing a fallback app bundle ID during target finalization on iOS. When finalizing an executable target on iOS, \l{qt6_finalize_target}{qt_finalize_target()} will populate the target's diff --git a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc index 02e85763e7..bb35d45cc3 100644 --- a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc @@ -32,7 +32,7 @@ \title qt_add_big_resources \target qt6_add_big_resources -\brief Compiles big binary resources into object code. +\summary Compiles big binary resources into object code. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc index b432037f8c..38c59c4174 100644 --- a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc @@ -32,7 +32,7 @@ \title qt_add_binary_resources \target qt6_add_binary_resources -\brief Creates an \c{RCC} file from a list of Qt resource files. +\summary Creates an RCC file from a list of Qt resource files. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc index 5248a12ed0..95bd9ee9bc 100644 --- a/src/corelib/doc/src/cmake/qt_add_executable.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc @@ -32,7 +32,7 @@ \title qt_add_executable \target qt6_add_executable -\brief Creates and finalizes an application target of a platform-specific type. +\summary Creates and finalizes an application target of a platform-specific type. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc index f2b9042b72..ffb50025f7 100644 --- a/src/corelib/doc/src/cmake/qt_add_library.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -32,7 +32,7 @@ \title qt_add_library \target qt6_add_library -\brief Creates and finalizes a library. +\summary Creates and finalizes a library. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc index 59c11ad6c7..9954ef341d 100644 --- a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -32,7 +32,7 @@ \title qt_add_plugin \target qt6_add_plugin -\brief Creates a Qt plugin target. +\summary Creates a Qt plugin target. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_add_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_resources.qdoc index af903721b6..cd6c8ce42e 100644 --- a/src/corelib/doc/src/cmake/qt_add_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_resources.qdoc @@ -32,7 +32,7 @@ \title qt_add_resources \target qt6_add_resources -\brief Compiles binary resources into source code. +\summary Compiles binary resources into source code. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc index 02aa9f316e..f3021602a5 100644 --- a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc +++ b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc @@ -32,7 +32,7 @@ \title qt_allow_non_utf8_sources \target qt6_allow_non_utf8_sources -\brief Prevent forcing source files to be treated as UTF-8 for Windows. +\summary Prevents forcing source files to be treated as UTF-8 for Windows. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc index afb31d6749..fd2e531461 100644 --- a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc @@ -32,7 +32,7 @@ \title qt_android_add_apk_target \target qt6_android_add_apk_target -\brief Defines a build target that runs androiddeployqt to produce an APK. +\summary Defines a build target that runs androiddeployqt to produce an APK. \preliminarycmakecommand \cmakecommandandroidonly diff --git a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc index 6d11d2ae14..c6f912cce9 100644 --- a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc @@ -32,7 +32,7 @@ \title qt_android_apply_arch_suffix \target qt6_android_apply_arch_suffix -\brief Configures the target binary's name to include an architecture-specific suffix. +\summary Configures the target binary's name to include an architecture-specific suffix. \preliminarycmakecommand \cmakecommandandroidonly diff --git a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc index e7880b7256..80a9d89919 100644 --- a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -32,7 +32,7 @@ \title qt_android_generate_deployment_settings \target qt6_android_generate_deployment_settings -\brief Generates the deployment settings file needed by androiddeployqt. +\summary Generates the deployment settings file needed by androiddeployqt. \preliminarycmakecommand \cmakecommandandroidonly diff --git a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc index b70a7b9f92..df93117819 100644 --- a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc +++ b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc @@ -32,7 +32,7 @@ \title qt_disable_unicode_defines \target qt6_disable_unicode_defines -\brief Prevents some unicode-related compiler definitions being set automatically on a target. +\summary Prevents some unicode-related compiler definitions being set automatically on a target. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc index 4a1b0c551c..af162fa63e 100644 --- a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -32,7 +32,7 @@ \title qt_extract_metatypes \target qt6_extract_metatypes -\brief Extracts metatypes from a Qt target and generates an associated metatypes.json file. +\summary Extracts metatypes from a Qt target and generates an associated metatypes.json file. \preliminarycmakecommand diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc index 408b4fb4b0..9aee8c0b0e 100644 --- a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc @@ -32,7 +32,7 @@ \title qt_finalize_target \target qt6_finalize_target -\brief Handles various common platform-specific tasks associated with Qt targets. +\summary Handles various common platform-specific tasks associated with Qt targets. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc index 5031204b0b..e3ee021b5a 100644 --- a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc +++ b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc @@ -32,7 +32,7 @@ \title qt_generate_moc \target qt6_generate_moc -\brief Calls moc on an input file. +\summary Calls moc on an input file. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc index cf0af9729c..dcb0c4e984 100644 --- a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -32,7 +32,7 @@ \title qt_import_plugins \target qt6_import_plugins -\brief Specifies a custom set of plugins to import for a static Qt build. +\summary Specifies a custom set of plugins to import for a static Qt build. \section1 Synopsis diff --git a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc index 7697920b44..909100de72 100644 --- a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc +++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc @@ -32,7 +32,7 @@ \title qt_set_finalizer_mode \target qt6_set_finalizer_mode -\brief Customizes aspects of a target's finalization. +\summary Customizes aspects of a target's finalization. \preliminarycmakecommand diff --git a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc index e6fe699129..acbbeae2e3 100644 --- a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -32,7 +32,7 @@ \title qt_wrap_cpp \target qt6_wrap_cpp -\brief Creates \c{.moc} files from sources. +\summary Creates .moc files from sources. \section1 Synopsis diff --git a/src/dbus/doc/src/qtdbus-cmake.qdoc b/src/dbus/doc/src/qtdbus-cmake.qdoc index f4432fb741..6968bb5a69 100644 --- a/src/dbus/doc/src/qtdbus-cmake.qdoc +++ b/src/dbus/doc/src/qtdbus-cmake.qdoc @@ -32,7 +32,7 @@ \title qt_add_dbus_interface \target qt6_add_dbus_interface -\brief Generates C++ sources implementing an interface for a D-Bus interface +\summary Generates C++ sources implementing an interface for a D-Bus interface description file. \section1 Synopsis @@ -94,9 +94,9 @@ Options can be set using \c set_source_file_property on the \c dbus_spec: \ingroup cmake-commands-qtdbus \title qt_add_dbus_interfaces -\target qt6_add_dbus_interface +\target qt6_add_dbus_interfaces -\brief Generates C++ sources implementing interfaces for D-Bus interface +\summary Generates C++ sources implementing interfaces for D-Bus interface description files. \section1 Synopsis @@ -153,7 +153,7 @@ arguments: \title qt_generate_dbus_interface \target qt6_generate_dbus_interface -\brief Generates a D-Bus interface from a header file. +\summary Generates a D-Bus interface from a header file. \section1 Synopsis @@ -188,7 +188,7 @@ arguments to the tool can be set after \c{OPTIONS}. \title qt_add_dbus_adaptor \target qt6_add_dbus_adaptor -\brief Generates an adaptor class for a D-Bus interface. +\summary Generates an adaptor class for a D-Bus interface. \section1 Synopsis diff --git a/src/widgets/doc/src/cmake-macros.qdoc b/src/widgets/doc/src/cmake-macros.qdoc index c7a914f42d..f4662dee9f 100644 --- a/src/widgets/doc/src/cmake-macros.qdoc +++ b/src/widgets/doc/src/cmake-macros.qdoc @@ -32,7 +32,7 @@ \title qt_wrap_ui \target qt6_wrap_ui -\brief Creates sources for \c{.ui} files. +\summary Creates sources for .ui files. \section1 Synopsis