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.solo...@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-boun...@qt-project.org> on behalf of Kai Köhne via Development <development@qt-project.org> Sent: Friday, September 15, 2023 9:36 AM To: qt-development <development@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@qt-project.org https://lists.qt-project.org/listinfo/development
-- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
