> 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 <development-boun...@qt-project.org> on behalf of Paul Wicking via Development <development@qt-project.org> Sent: Friday, September 15, 2023 11:25 AM To: Edward Welbourne <edward.welbou...@qt.io> Cc: development@qt-project.org <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 <development@qt-project.org> 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
