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

[Edward Welbourne]

On 9/15/23 09:36, Kai Köhne via Development wrote:
>> 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.

Christian Kandeler (15 September 2023 10:31) wrote:
> Radical idea: Treat all deprecated functions as if they didn't exist,
> i.e. remove the documentation entirely. It seems counter-intuitive
> that legacy interfaces should take more documentation effort than
> current ones. Also, this way, fewer people will even be tempted to
> short-sightedly use them.

Tempting as that radical approach is, the temptation you're trying to
prevent is mostly avoided by hiding the docs of deprecated functions on
the -obsolete page; and we do have to think of folk who are trying to
work out what their existing code does.  It's hard to port away from an
old API if you don't have a clear description of what your old code was
achieving by using it, so as to be sure you've achieved the same result
with your use of the new API.  The documentation of a deprecated
function should, also, tell the reader what to use instead, to help them
work that out; they can't read that advice if it's not there.

	Eddy.