Kai Köhne (15 September 2023 09:36) wrote: > 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.
Note that QT_WARN_DEPRECATED_UP_TO provides the means to ignore warnings for things deprecated from even the current version, if you want. So a project can perfectly well set that to QT_VERSION_CHECK(6, 0, 0) and be saved deprecation warnings added since 6.0 - although, obviously, it would be prudent to build without that override at least sometimes, so they know what technical debt they're accumulating. > 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. As you observe, this has problems of coordination. > - 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? I suggest a third alternative: QDoc, when generating documention for a future deprecation, can treat it as current but, instead of phrasing that as "deprecated since x.y", express it as "deprecated and will start producing warnings about that from x.y" - or something similar. When it comes down to it, because the replacement should already be available by the time the old API is future-deprecated, omitting the old from the main API docs makes perfect sense: we don't want folk to add new uses of it, we'd much sooner they use the replacement already, and that should be present in the API docs. If they're looking up what the old API does in order to make sense of code using it, they'll still find it, but if they're looking at the class to find out how to do the thing the old API does, they'll find the new API instead and use that. Eddy. -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
