[Development] Proposal to retain \since version information in Qt Documentation

[Paul Wicking]

On 24 Sep 2024, at 17:48, Kai Köhne <Kai.Koehne at qt.io> wrote:

Just keep in mind that we weren't always strict about adding these in the past, so for
accurate results, git history is arguably the more reliable source. That is, unless you're
interested in changes that predate the big git import in Qt 4 times 😉

You raise an important point about the consistency of `\since` annotations in
the past. Indeed, we weren't always strict about adding them, and as a result,
the annotations may not be exhaustive or entirely accurate for all
features. While git history is a valuable resource for tracking changes,
especially for accurate results, it does have limitations—particularly for
changes that predate the major git import during Qt 4 times. In such cases, the
`\since` annotations can serve as a helpful guide without requiring developers
to delve deeply into the code history.

Anyhow, I think I would oppose trying to make https://doc.qt.io/qt-6/<https://doc.qt.io/qt-6/qtcore-index.html> documentation 'work' for
Qt 5, let alone Qt 4. For one, we have dropped documentation for removed modules,
removed API, abandoned platforms between major versions, and bringing these back is
IMO unfeasible. Sure, there are also classes that are still available since Qt 4, so for these
stable parts you could use Qt 6 documentation even if you write a Qt 4 hello-world.
But what for? https://doc.qt.io/qt-6/<https://doc.qt.io/qt-6/qtcore-index.html>  is the documentation for Qt 6. People that have to work
with Qt 5 are better off with  https://doc.qt.io/qt-5<https://doc.qt.io/qt-5/>, and for Qt 4.8 with
https://doc.qt.io/archives/qt-4.8/. So let's not imply that any API documentation on
https://doc.qt.io/qt-6 is anything but Qt 6. For changes between major versions, we have
dedicated 'What's new' pages.

I fully agree that doc.qt.io/qt-6 is intended for Qt 6, and we should not imply
that it serves as official documentation for earlier versions.

My proposal isn't to retrofit the Qt 6 documentation to accommodate older
versions but rather to retain the `\since` annotations in the source code. This
way, developers who might reference the Qt 6 documentation—even when working on
legacy systems—can gain insights into when certain features were introduced.

For one, we have dropped documentation for removed modules,
removed API, abandoned platforms between major versions, and bringing these back is
IMO unfeasible. Sure, there are also classes that are still available since Qt 4, so for these
stable parts you could use Qt 6 documentation even if you write a Qt 4 hello-world.
But what for? https://doc.qt.io/qt-6/<https://doc.qt.io/qt-6/qtcore-index.html>  is the documentation for Qt 6. People that have to work
with Qt 5 are better off with  https://doc.qt.io/qt-5<https://doc.qt.io/qt-5/>, and for Qt 4.8 with
https://doc.qt.io/archives/qt-4.8/. So let's not imply that any API documentation on
https://doc.qt.io/qt-6 is anything but Qt 6. For changes between major versions, we have
dedicated 'What's new' pages.

For stable classes and functions that have persisted since Qt 4, the `\since`
annotations provide valuable context. They help developers understand the
longevity and evolution of certain APIs, which can be beneficial even when the
primary focus is on Qt 6.

If we stick to this for the generated documentation, \since tags for older Qt versions in the
source code don't do much harm. But the benefits are really small, either.
Should we just leave this to the individual maintainer to decide?

I think having a consistent policy across the project would be more
beneficial. This approach would prevent fragmentation and ensure that all
modules adhere to the same documentation standards.

--
//! Paul
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240925/8b9f4981/attachment-0001.htm>