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

[Kai Köhne]

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