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

[Elvis Stansvik]

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 at qt-project.org>:
>
>
>
> 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/ 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 at qt-project.org
> https://lists.qt-project.org/listinfo/development