From 5512e03562694ebfe571a3b6068a7d35d9ddfd7a Mon Sep 17 00:00:00 2001 From: "Friedrich W. H. Kossebau" Date: Sat, 17 Apr 2021 11:02:00 +0200 Subject: Modules docs: move rst docs into bracket comments CMake >= 3.0 supports bracket comments, and the reStructuredText integration code in sphinx/ext/ecm.py already supports extracting the docs from a bracket comment instead. Editing documentation without leading line comment markers is more simple, e,g. when reflowing text over lines. With ECM meanwhile requiring CMake 3.5 now it is possible to switch (and thus follow also the approach used by cmake itself). NO_CHANGELOG --- modules/ECMQtDeclareLoggingCategory.cmake | 290 +++++++++++++++--------------- 1 file changed, 145 insertions(+), 145 deletions(-) (limited to 'modules/ECMQtDeclareLoggingCategory.cmake') diff --git a/modules/ECMQtDeclareLoggingCategory.cmake b/modules/ECMQtDeclareLoggingCategory.cmake index a6562333..7de5ae9b 100644 --- a/modules/ECMQtDeclareLoggingCategory.cmake +++ b/modules/ECMQtDeclareLoggingCategory.cmake @@ -1,153 +1,153 @@ -#.rst: -# ECMQtDeclareLoggingCategory -# --------------------------- -# -# This module provides the ``ecm_qt_declare_logging_category`` function for -# generating declarations for logging categories in Qt5, and the -# ``ecm_qt_install_logging_categories`` function for generating and installing -# a file in KDebugSettings format with the info about all those categories, -# as well as a file with info about any renamed categories if defined. -# To include in that file any logging categories that are manually defined -# also a function ``ecm_qt_export_logging_category`` is provided. -# -# :: -# -# ecm_qt_declare_logging_category( -# HEADER -# IDENTIFIER -# CATEGORY_NAME -# [OLD_CATEGORY_NAMES [ [...]]] -# [DEFAULT_SEVERITY ] -# [EXPORT ] -# [DESCRIPTION ] -# ) -# -# A header file, ````, will be generated along with a corresponding -# source file. These will provide a QLoggingCategory category that can be referred -# to from C++ code using ````, and from the logging configuration using -# ````. -# -# The generated source file will be added to the variable with the name -# ````. If the given argument is a target though, instead both the -# generated header file and the generated source file will be added to the target as -# private sources (since 5.80). -# -# If ```` is not absolute, it will be taken relative to the current -# binary directory. -# -# If the code is compiled against Qt 5.4 or later, by default it will only log -# output that is at least the severity specified by ``DEFAULT_SEVERITY``, or -# "Info" level if ``DEFAULT_SEVERITY`` is not given. Note that, due to a -# bug in Qt 5.5, "Info" may be treated as more severe than "Fatal". -# -# ```` may include namespaces (eg: ``foo::bar::IDENT``). -# -# If ``EXPORT`` is passed, the category will be registered for the group id -# ````. Info about the categories of that group can then be -# generated in a file and installed by that group id with the -# ``ecm_qt_install_logging_categories`` function. In that case also ``DESCRIPTION`` -# will need to be passed, with ```` being a short single line text. -# And ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, -# so user settings can be migrated. Since 5.68.0. -# -# Since 5.14.0. -# -# :: -# -# ecm_qt_export_logging_category( -# IDENTIFIER -# CATEGORY_NAME -# [OLD_CATEGORY_NAMES [ [...]]] -# EXPORT -# DESCRIPTION -# [DEFAULT_SEVERITY ] -# ) -# -# Registers a logging category for being included in the generated and -# installed KDebugSettings files. To be used for categories who are declared by -# manual code or other ways instead of code generated with -# ``ecm_qt_declare_logging_category``. -# -# ```` may include namespaces (eg: ``foo::bar::IDENT``). -# -# ``EXPORT`` specifies the group id with which the category will be registered. -# Info about the categories of that group can then be generated in a file and -# installed by that group id with the ``ecm_qt_install_logging_categories`` function. -# -# ``DESCRIPTION`` specifies a short single line text describing the category. -# -# ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, -# so user settings can be migrated. -# -# Since 5.68.0. -# -# :: -# -# ecm_qt_install_logging_categories( -# EXPORT -# [FILE ] -# DESTINATION -# [SORT] -# [COMPONENT ] -# ) -# -# Generates and installs a file in KDebugSettings format with the info about all -# the categories registered for the group ````, as well as a file with -# info about any renamed categories, if there are. -# -# The method call needs to be after the last ``ecm_qt_declare_logging_category`` -# call which uses the same ````. This can be in the same directory, or -# any subdirectory or parent directory. -# -# ``EXPORT`` specifies the group id of categories whose information should be -# stored in the file generated and installed. -# -# ``FILE`` specifies the name of the file generated and installed. It will default -# to lower-cased ``.categories``. -# -# ``DESTINATION`` specifies where the generated file will be -# installed. -# -# IF ``SORT`` is set, entries will be sorted by identifiers. -# -# ``COMPONENT`` specifies the installation component name with which the install -# rules for the generated file are associated. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_qt_declare_logging_category( -# MYPROJECT_SRCS -# HEADER "myproject_debug.h" -# IDENTIFIER "MYPROJECT_DEBUG" -# CATEGORY_NAME "myproject" -# OLD_CATEGORY_NAMES "myprojectlog" -# DESCRIPTION "My project" -# EXPORT MyProject -# ) -# -# ecm_qt_export_logging_category( -# IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG" -# CATEGORY_NAME "myproject.submodule" -# DESCRIPTION "My project - submodule" -# EXPORT MyProject -# ) -# -# ecm_qt_install_logging_categories( -# EXPORT MyProject -# FILE myproject.categories -# DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}" -# ) -# -# Since 5.68.0. - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Merry # SPDX-FileCopyrightText: 2020 Friedrich W. H. Kossebau # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMQtDeclareLoggingCategory +--------------------------- + +This module provides the ``ecm_qt_declare_logging_category`` function for +generating declarations for logging categories in Qt5, and the +``ecm_qt_install_logging_categories`` function for generating and installing +a file in KDebugSettings format with the info about all those categories, +as well as a file with info about any renamed categories if defined. +To include in that file any logging categories that are manually defined +also a function ``ecm_qt_export_logging_category`` is provided. + +:: + + ecm_qt_declare_logging_category( + HEADER + IDENTIFIER + CATEGORY_NAME + [OLD_CATEGORY_NAMES [ [...]]] + [DEFAULT_SEVERITY ] + [EXPORT ] + [DESCRIPTION ] + ) + +A header file, ````, will be generated along with a corresponding +source file. These will provide a QLoggingCategory category that can be referred +to from C++ code using ````, and from the logging configuration using +````. + +The generated source file will be added to the variable with the name +````. If the given argument is a target though, instead both the +generated header file and the generated source file will be added to the target as +private sources (since 5.80). + +If ```` is not absolute, it will be taken relative to the current +binary directory. + +If the code is compiled against Qt 5.4 or later, by default it will only log +output that is at least the severity specified by ``DEFAULT_SEVERITY``, or +"Info" level if ``DEFAULT_SEVERITY`` is not given. Note that, due to a +bug in Qt 5.5, "Info" may be treated as more severe than "Fatal". + +```` may include namespaces (eg: ``foo::bar::IDENT``). + +If ``EXPORT`` is passed, the category will be registered for the group id +````. Info about the categories of that group can then be +generated in a file and installed by that group id with the +``ecm_qt_install_logging_categories`` function. In that case also ``DESCRIPTION`` +will need to be passed, with ```` being a short single line text. +And ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, +so user settings can be migrated. Since 5.68.0. + +Since 5.14.0. + +:: + + ecm_qt_export_logging_category( + IDENTIFIER + CATEGORY_NAME + [OLD_CATEGORY_NAMES [ [...]]] + EXPORT + DESCRIPTION + [DEFAULT_SEVERITY ] + ) + +Registers a logging category for being included in the generated and +installed KDebugSettings files. To be used for categories who are declared by +manual code or other ways instead of code generated with +``ecm_qt_declare_logging_category``. + +```` may include namespaces (eg: ``foo::bar::IDENT``). + +``EXPORT`` specifies the group id with which the category will be registered. +Info about the categories of that group can then be generated in a file and +installed by that group id with the ``ecm_qt_install_logging_categories`` function. + +``DESCRIPTION`` specifies a short single line text describing the category. + +``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, +so user settings can be migrated. + +Since 5.68.0. + +:: + + ecm_qt_install_logging_categories( + EXPORT + [FILE ] + DESTINATION + [SORT] + [COMPONENT ] + ) + +Generates and installs a file in KDebugSettings format with the info about all +the categories registered for the group ````, as well as a file with +info about any renamed categories, if there are. + +The method call needs to be after the last ``ecm_qt_declare_logging_category`` +call which uses the same ````. This can be in the same directory, or +any subdirectory or parent directory. + +``EXPORT`` specifies the group id of categories whose information should be +stored in the file generated and installed. + +``FILE`` specifies the name of the file generated and installed. It will default +to lower-cased ``.categories``. + +``DESTINATION`` specifies where the generated file will be +installed. + +IF ``SORT`` is set, entries will be sorted by identifiers. + +``COMPONENT`` specifies the installation component name with which the install +rules for the generated file are associated. + +Example usage: + +.. code-block:: cmake + + ecm_qt_declare_logging_category( + MYPROJECT_SRCS + HEADER "myproject_debug.h" + IDENTIFIER "MYPROJECT_DEBUG" + CATEGORY_NAME "myproject" + OLD_CATEGORY_NAMES "myprojectlog" + DESCRIPTION "My project" + EXPORT MyProject + ) + + ecm_qt_export_logging_category( + IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG" + CATEGORY_NAME "myproject.submodule" + DESCRIPTION "My project - submodule" + EXPORT MyProject + ) + + ecm_qt_install_logging_categories( + EXPORT MyProject + FILE myproject.categories + DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}" + ) + +Since 5.68.0. +#]=======================================================================] + include(CMakeParseArguments) set(_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_CPP "${CMAKE_CURRENT_LIST_DIR}/ECMQtDeclareLoggingCategory.cpp.in") -- cgit v1.2.1