Den ons 25 sep. 2024 kl 21:23 skrev Elvis Stansvik <elvst...@gmail.com>: > > 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.
Actually I may be wrong about the above and \since 5.x was never shown in the published online docs Qt 6 on doc.qt.io, I'm not sure. If so I must have been thinking of the times when "qstring 5" first hit was showing up e.g. Qt 5.15, but I was stuck on Qt 5.12 or Qt 5.9 or. Anyway, if so, the \since were very useful even if showing up only for minor releases within a single major version. In the work I did, we were limited to what *buntu LTS was shipping, so it was often the case that we were limited to say 5.6.x or 5.9.x, while 5.12 or 5.15 might have been the latest version. Elvis > > 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
