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

[Topi Reiniö via Development]

> I'm not sure how viable this is, it's just an idea off the top of my head: we 
> could perhaps implement support
> for "from/until" e.g. in the class members section, similar to what's on 
> cppreference.com<http://cppreference.com> (e.g. void foo()
> [since 5.15, until 6.5]). The docs for something that's gone could then 
> possibly link to the published docs for
> the last version (defined by whatever sets the "until" version) that 
> particular feature is documented in, such
> that the members list for e.g. 6.7 would carry members that don't exist in 
> 6.7 but link to the last known state
> of that member. Then we could drop the -obsolete pages entirely (they 
> sometimes confuse  search engines,
> so that's an argument in favor of getting rid of them) and we'd point users 
> of older Qt versions to versions of
> the docs that are possibly more relevant for them anyway.

Yes, having QDoc support both 'since' and 'until', presented in the same 
context, would be an improvement.
Potentially, QDoc could also parse the deprecation macros and apply them to 
documentation, or ideally,
warn the author about missing deprecation docs. This would be useful to ensure 
that the 'use this instead'
information, as mentioned by Eddy, is available. Dropping deprecated docs in 
favor of linking to old archives
would mean we'd likely lose that bit of useful info. There's a benefit of 
having all the docs in a self-contained
set as well.

-Topi

From: Development  on behalf of Paul 
Wicking via Development 
Sent: Friday, September 15, 2023 11:25 AM
To: Edward Welbourne 
Cc: development@qt-project.org 
Subject: Re: [Development] How to document API only deprecated in future Qt 
versions



On 15 Sep 2023, at 10:44, Edward Welbourne via Development 
 wrote:

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.

I'm not sure how viable this is, it's just an idea off the top of my head: we 
could perhaps implement support for "from/until" e.g. in the class members 
section, similar to what's on cppreference.com<http://cppreference.com> (e.g. 
void foo() [since 5.15, until 6.5]). The docs for something that's gone could 
then possibly link to the published docs for the last version (defined by 
whatever sets the "until" version) that particular feature is documented in, 
such that the members list for e.g. 6.7 would carry members that don't exist in 
6.7 but link to the last known state of that member. Then we could drop the 
-obsolete pages entirely (they sometimes confuse  search engines, so that's an 
argument in favor of getting rid of them) and we'd point users of older Qt 
versions to versions of the docs that are possibly more relevant for them 
anyway.

//! Paul

Eddy.
--
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

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

[Paul Wicking via Development]

On 15 Sep 2023, at 10:44, Edward Welbourne via Development 
 wrote:

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.

I'm not sure how viable this is, it's just an idea off the top of my head: we 
could perhaps implement support for "from/until" e.g. in the class members 
section, similar to what's on cppreference.com (e.g. 
void foo() [since 5.15, until 6.5]). The docs for something that's gone could 
then possibly link to the published docs for the last version (defined by 
whatever sets the "until" version) that particular feature is documented in, 
such that the members list for e.g. 6.7 would carry members that don't exist in 
6.7 but link to the last known state of that member. Then we could drop the 
-obsolete pages entirely (they sometimes confuse  search engines, so that's an 
argument in favor of getting rid of them) and we'd point users of older Qt 
versions to versions of the docs that are possibly more relevant for them 
anyway.

//! Paul

Eddy.
--
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

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

[Edward Welbourne via Development]

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.
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

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

[Christian Kandeler via Development]

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.


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.



Christian

--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

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

[Ivan Solovev via Development]

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  on behalf of Kai Köhne 
via Development 
Sent: Friday, September 15, 2023 9:36 AM
To: qt-development 
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 | 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

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

[Edward Welbourne via Development]

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

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

[Kai Köhne via Development]

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 | 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