Distinguish between deprecated and to-be-removed methods

Introduction

At the QtCS 2024 we discussed the problem with a large amount of deprecated methods, and the conclusion was that deprecation does not necessarily mean that the deprecated functions will be removed in the next Qt major version (Qt 7). However, we really want some APIs to be gone in Qt 7.

As a result, we need a way to distinguish between the deprecated and deprecated and to-be-removed methods.

Current situation

Currently the deprecation is done in the following way:

// myclass.h
class MyClass
{
    // other methods and members
#if QT_DEPRECATED_SINCE(6, 8)
    QT_DEPRECATED_VERSION_X_6_8("Use some other thing")
    void myDeprecatedMethod();
#endif // QT_DEPRECATED_SINCE(6, 8)
};

// myclass.cpp
#if QT_DEPRECATED_SINCE(6, 8)
/*!
    \deprecated [6.8] Use something else.
    Docs for the function
*/
void MyClass::myDeprecatedMethod()
{
    // implementation
}
#endif // QT_DEPRECATED_SINCE(6, 8)

The QT_DEPRECATED_VERSION_X_... macro is responsible for the generation of the actual deprecation warning, while the QT_DEPRECATED_SINCE macro checks the value of QT_DISABLE_DEPRECATED_UP_TO definition to see if the function should be removed (entirely, from the API and ABI) or not.

Currently our build system defines QT_DISABLE_DEPRECATED_UP_TO to a value of 0x050000, which is Qt 5.0. The conclusion at the QtCS was that we will not automatically raise this value when switching to Qt 7.

However, there are custom builds of Qt that can set this value to a higher version in order to actually get rid of all deprecated methods. For example, our CI has a qtlite build that defines QT_DISABLE_DEPRECATED_UP_TO=0x070000 (Qt 7). This should still work.

How to distinguish between deprecated and to-be-removed functions?

Below are some ideas that may be considered:

1. Use QT_VERSION_CHECK.
If we want the deprecated function to be removed in Qt 7, we can simply add an extra QT_VERSION_CHECK on top of all the deprecation macros:

// myclass.h
#if QT_VERSION < QT_VERSION_CHECK(7, 0, 0)
#if QT_DEPRECATED_SINCE(6, 8)
QT_DEPRECATED_VERSION_X_6_8("Use some other thing")
void myDeprecatedMethod();
#endif // QT_DEPRECATED_SINCE(6, 8)
#endif // QT_VERSION < QT_VERSION_CHECK(7, 0, 0)

// myclass.cpp
// similarly in the implementation

This way, the function will exist until Qt 7, and can still be optionally removed using QT_DISABLE_DEPRECATED_UP_TO.

2. Create a new macro that will combine QT_VERSION_CHECK and QT_DEPRECATED_SINCE.

In both cases we will need to adjust the docs manually. This can be done by either updating the description string of the \deprecated qdoc command, or introducing a brand new qdoc command.
Something like:

\removed [7.0]

which will expand into

This function will be removed in Qt 7.0.

Next steps

When we sort out the implementation details, the next step will be to decide which functions should be marked as to-be-removed in Qt 7.