Create Task
Maniphest T12741

Central location to define and document all Qt logging categories in a repo
Open, Needs TriagePublic
Actions

Description

PROBLEMS

There are documentation/discovery-related issues currently when it comes to categories used by KF modules for the Qt Logging infrastructure :

  • usually no good description/definition about the scope, especially for subcategories
  • no central place where to look up the present category names, code has to be searched

The category names in use are usually hidden away in the codebase, either in ecm_qt_declare_logging_category() calls distributed over the CMakeLists.txt files or even only in C++ sources in the Q_LOGGING_CATEGORY()calls. The .categories files for kdebugsettings help a bit, but one has to know they exist and where to find them. There is no defined central place in the codebase (even more with .categories files now being generated by ecm_qt_install_logging_categories() calls only in the build.
So a developer working on a KF module who wants to add new logging needs to search around first.

Similar case for developer or user using a KF module who wants to control logging. They cannot look up the existing categories e.g. in the API documentation, but instead have to browse the source as well.

Qt base modules seem to lack proper documentation as well, though some none-base modules list theirs, e.g.:

WANTED

Required:

  1. have a central file per repository which has all data about all categories
  2. have ECM macros (ecm_qt_declare_logging_category(), ecm_qt_install_logging_categories()) generate anything based on that central file
  3. have API documentation generation tools (kapidox: source-only, ECMAddQCH: build-time) automatically generate docs about the available categories that file contain all data needed to generate content to include in the API documentation

Nice to have:

  1. Ensuring supercategories are consistent, typos are catched
  2. Concepts of KF category patterns mapped in the file syntax

PROPOSED SOLUTION (draft text, incomplete)

There would be a new file format for a file (.qlogcats) which has all metadata about logging categories used in a project. The format could be parsed both from CMake (ECM) & Python (kapidox) as well as edited directly by developers with ease in a plain text editor.

Example (kcoreaddons):

[QLoggingCategory Metadata]

[Category:kf.kcoreaddons]
Name=KCoreAddons
Description=KCoreAddons
DocsDescription=global category
Identifier=KCOREADDONS_DEBUG

[Category:kf.kcoreaddons.kdirwatch]
Description=KCoreAddons: KDirWatch
DocsDescription=KDirWatch class
Identifier=KDIRWATCH
DefaultSeverity=Warning
OldCategoryNames=

[Category:kf.kcoreaddons.kaboutdata]
Description=KCoreAddons: KAboutData
DocsDescription=KAboutData class
Identifier=KABOUTDATA

[Category:kf.kcoreaddons.desktopparser]
Description=KCoreAddons: DesktopParser
DocsDescription=parsing of Desktop files
DefaultSeverity=Warning
Identifier=DESKTOPPARSER

[Category:kf.kcoreaddons.kdelibs4configmigrator]
Description=KCoreAddons: Kdelibs4ConfigMigrator
DocsDescription=migration of KDE4-type config
DefaultSeverity=Warning
Identifier=MIGRATOR

The data in the file could be used to generate content for the API documentation, like an additional file in Markdown format which then would be added to the sources to cover by Doxygen. The description text would be different to the one used for KDebugSettings, as the API dox has a defined context already, so e.g. does not need the explicit mention of the repository name for subcategories, whereas in KDebugSettings each description has to work on its own.

Example (kcoreaddons):

## Logging Categories

The following logging categories exists:
Logging Category | Description
---------------- | -----------
kf.kcoreaddons | KCoreAddons global 
kf.kcoreaddons.kdirwatch | KDirWatch class
kf.kcoreaddons.kaboutdata | KAboutData class
kf.kcoreaddons.desktopparser | parsing of Desktop files
kf.kcoreaddons.kdelibs4configmigrator | migration of KDE4-type config

To generate that file, both KApiDox and ECMQtDeclareLoggingCategory would have each implementation to do that, as sharing a single code might be not feasible. ECMQtDeclareLoggingCategory would have a macro to parse in that file and make the data available to variants of ecm_qt_declare_logging_category() and ecm_qt_install_logging_categories() as well as generate the file, which then would be added as another SOURCES element in the ecm_add_qch() call.

Related Objects

kossebau updated the task description. (Show Details)Feb 24 2020, 11:23 AM
kossebau updated the task description. (Show Details)Apr 27 2020, 1:49 PM
ahiemstra added a subscriber: ahiemstra.Apr 6 2021, 12:16 PM

@kossebau I wonder if the new JSON parsing functionality of CMake can help here? It'd mean changing the config to use JSON, but it would avoid the entire parsing stuff.

So you'd have something like this as input:

[
    {
        "Category": "kf.kcoreaddons",
        "Name": "KCoreAddons",
        "Description": "KCoreAddons",
        "DocsDescription": "global category",
        "Identifier": "KCOREADDONS_DEBUG"
    },
    {
        "Category": "kf.kcoreaddons.kdirwatch",
        "Description": "KCoreAddons: KDirWatch",
        "DocsDescription": "KDirWatch class",
        "Identifier": "KDIRWATCH",
        "DefaultSeverity": "Warning",
        "OldCategoryNames": ""
    },
    {
        "Category": "kf.kcoreaddons.kaboutdata",
        "Description": "KCoreAddons: KAboutData",
        "DocsDescription": "KAboutData class",
        "Identifier": "KABOUTDATA"
    },
    {
        "Category": "kf.kcoreaddons.desktopparser",
        "Description": "KCoreAddons: DesktopParser",
        "DocsDescription": "parsing of Desktop files",
        "DefaultSeverity": "Warning",
        "Identifier": "DESKTOPPARSER"
    },
    {
        "Category": "kf.kcoreaddons.kdelibs4configmigrator",
        "Description": "KCoreAddons: Kdelibs4ConfigMigrator",
        "DocsDescription": "migration of KDE4-type config",
        "DefaultSeverity": "Warning",
        "Identifier": "MIGRATOR"
    }
]

Which would be processed by some CMake like this:

file(READ loggingcategories "qloggingcategories.json")
string(JSON categorycount LENGTH ${loggingcategories})
foreach(index RANGE ${categorycount})
    string(JSON category GET ${loggingcategories} ${index})
    
    string(JSON name GET ${category} "Category")
    string(JSON identifier GET ${category} "Identifier")
    string(JSON description GET ${category} "Description")
    
    ecm_qt_declare_logging_category(sources 
        HEADER qloggingcategories.h 
        CATEGORY_NAME ${name}
        IDENTIFIER ${identifier}
    )
endforeach()

Of course with appropriate error handling and such added.

kossebau added a comment.Apr 6 2021, 12:45 PM

Ah, did not know about the JSON support yet. Seems that is new in CMake 3.19? That might be a small bummer, given we want to have something working with versions before, matching the official min required one, which will be 3.16 soon only still if I got it right.

Having built-in support for parsing would be a +1 for choosing JSON as base format (even though I personally dislike that format when targetting human editors for certain reasons), agreeing there.

alex awarded a token.Aug 21 2021, 7:13 PM