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

[Elvis Stansvik]

Den ons 25 sep. 2024 kl 21:23 skrev Elvis Stansvik <elvstone at 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 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