[Development] How to document API only deprecated in future Qt versions

[Ivan Solovev]

Hi,

> I see two fixes for this;
> - Keep the documentation API fix separate from the header file fix, and only merge it when Qt 6.9 got branched.
> This requires 'someone' to follow up on these things, though, more than a year after the deprecation decision has been made.

This approach will help to solve some inconsistencies that I will describe below, but I do not believe that it will work in practice.
We will simply forget about the doc udpates.

> - Deprecate the API already _in the documentation_ for 6.6, but only follow up with the compiler warning in Qt 6.10.

This might lead to confusion in some corner cases.
For example, when doing a Qt build with QT_DISABLE_DEPRECATED_UP_TO.
Based on the documentation, the users will expect that the function is removed from the build, but it will still be there.
Not sure how critical this is in practice.


We could solve the problem if we could automate the first suggestion - create some script that will recognize
the QT_DEPRECATED_VERSION macro (and all its variations) for the specific Qt version and adjust the docs accordingly.
Probably QDoc could be extended to support a feature like this.
Then, simply running this script to find and fix all deprecations in Qt MAJ.MIN before creating the MAJ.MIN.0 branch should help.

I'm not sure how feasible it would be in practice, though.

Best regards,
Ivan

------------------------------

Ivan Solovev
Senior Software Engineer

The Qt Company GmbH
Erich-Thilo-Str. 10
12489 Berlin, Germany
ivan.solovev at qt.io
www.qt.io

Geschäftsführer: Mika Pälsi,
Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht
Charlottenburg, HRB 144331 B
________________________________
From: Development <development-bounces at qt-project.org> on behalf of Kai Köhne via Development <development at qt-project.org>
Sent: Friday, September 15, 2023 9:36 AM
To: qt-development <development at qt-project.org>
Subject: [Development] How to document API only deprecated in future Qt versions

Hi,

Eddy and Ivan did a great job in documenting how to formally deprecate API in at https://wiki.qt.io/Deprecation . It's not only giving you the right macros to use ... it also contains some suggestions for which version to do it.

About the Qt version to deprecate an API for, the page says:

     When deprecating an old API in favor of a new one, it is a kindness to client code
     maintainers to set the version at which the deprecation takes effect to a future version,
     such as three minor versions after the new API was added, to give ample time to adapt
     to it. All the same, you must prepare all of Qt's code for the transition promptly, as if
     the deprecation took effect as soon as its commit integrated.

I see why this 'conservative' approach is beneficial. Projects like Qt Creator tend to support multiple Qt versions, and immediately deprecating an old API in the same version the replacement API got added makes this hard to handle.\

Anyhow, it creates a challenge for documentation. Take e.g.

https://doc-snapshots.qt.io/qt6-6.6/qtfuture-obsolete.html

The methods are formally marked as deprecated for Qt 6.10. But the methods are already in the '-obsolete' page for Qt 6.6, which leaves the API in a weird in-between state.

I see two fixes for this;
- Keep the documentation API fix separate from the header file fix, and only merge it when Qt 6.9 got branched. This requires 'someone' to follow up on these things, though, more than a year after the deprecation decision has been made.
- Deprecate the API already _in the documentation_ for 6.6, but only follow up with the compiler warning in Qt 6.10.

I'm actually in favor of the second approach; documentation is mostly read when writing _new_ code, and that should already be written with the new API. But it's not something we've done so far, IMO.

Do you agree?

Kai

--
Kai Köhne, Director R&D | The Qt Company

The Qt Company GmbH, Erich-Thilo-Str. 10, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B

--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230915/e4f5c8db/attachment-0001.htm>