Just to chime in as a user, the \since annotations have been very useful for me and I've used them extensively.
In Qt 5 times, my usual workflow for finding QString docs used to be googling "qstring" and pressing the first hit. When Qt 6 came along and googling "qstring" gave the Qt 6 page as first hit, and I was still relagated to having to support Qt 5, I started googling "qstring 5" instead, which would give the Qt 5 docs page as first hit. Since Qt 6 docs SEO and Qt 6 popularity improved "qstring 5" started showing the Qt 6 docs page, but I was still relegated to having to support Qt 5, I started pressing the Qt 6 page instead, and it was mostly OK to use that - the \since information would tell me if it was Qt 6 only. I realize \since has not been used diligently, but it's still very useful. I think it's OK that it only shows one \since for major release back, hopefully not that many have to support current_major - 2. Leaving them in forever sounds reasonable to me though. For people that need to support current_major - 2, it can be useful for them to just Git clone latest version and see it there, without having to wade through Git history. I don't understand why people think it's noise.. it's one line? Elvis Den ons 25 sep. 2024 kl 21:03 skrev Paul Wicking via Development <development@qt-project.org>: > > > > 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/ > 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/ is the documentation for Qt 6. People > that have to work > with Qt 5 are better off with 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/ is the documentation for Qt 6. People > that have to work > with Qt 5 are better off with 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 -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
