[Development] On deprecating functions

Martin Smith Martin.Smith at qt.io
Tue Mar 5 08:37:21 CET 2019


When qdoc sees the function declaration, it must be able to mark the qdoc node for the declaration as deprecated in 5.13, for example, so that it can require that the deprecation be mentioned in the function documentation.

martin

________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Lars Knoll <lars.knoll at qt.io>
Sent: Tuesday, March 5, 2019 8:14 AM
To: Christian Ehrlicher
Cc: Qt development mailing list
Subject: Re: [Development] On deprecating functions



On 5 Mar 2019, at 06:56, Christian Ehrlicher <Ch.Ehrlicher at gmx.de<mailto:Ch.Ehrlicher at gmx.de>> wrote:

Am 05.03.2019 um 00:37 schrieb André Pönitz:
On Mon, Mar 04, 2019 at 03:12:33PM -0800, Thiago Macieira wrote:
On Monday, 4 March 2019 13:48:25 PST André Pönitz wrote:
The proposed model would effectively introduce another user-visible
level including associated period of time between "alternative
solution gets introducd" and "getting nagged about not using it"
that is "hopefully" long enough, to cover "most interesting"
(to be blunt: read: "including my") use case.
I don't think we should deprecate things, much less warn about, until there's
a suitable example, except in few cases where the API was mis-designed and has
no solution. That doesn't mean the solution needs to be a simple search-and-
replace, but it needs to exist.

Does that change what you're proposing?
There's a difference in so far that I request a certain period of time
(or rather, a span of Qt versions) both, old and new version, compile
and do not cause a warning in a default Qt build.
We could add a new define similar to QT_DISABLE_DEPRECATED_BEFORE - QT_DEPRECATED_WARNINGS_BEFORE which is by default initialized to the same value as QT_DISABLE_DEPRECATED_BEFORE but can be set to something else if needed.

One solution I thought about is to replace the QT_DEPRECATED(_X) macros with something that also contains the version (similar to QT_DEPRECATED_SINCE). Then the user could define how current he wants to be, and we could set a reasonable default going e.g. one LTS back.

So use something like

QT_WARN_DEPRECATED(5,13) void myDeprecatedFunction()

And expand it to wither QT_DEPRECATED or nothing depending on the version limit set.

Cheers,
Lars



More information about the Development mailing list