On 24 Sep 2024, at 17:48, Kai Köhne <kai.koe...@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
-- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
