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

[Jaroslaw Kobus]

This doesn't help much. To the original question: When the "\since" was introduced?

First what I did was to grep for "\since" string on qttools. Only 5 hits in scope of qttools/src/qdoc - not useful.
Then I've searched for "since" there: around ~200 hits.
By clicking on them I've concluded the crucial one may be: "Node::since()"
[qttools/src/qdoc/qdoc/src/qdoc/node.h - still not sure if I should focus on this] - then I git blame this line and got:
4c3108e5c2975e8ab07d4cb2c722bb100625656d - this is only a change that decorates the definition.
So, maybe I will be more lucky with blaming the current implementation in hope to see some lines of the introducing change?

I leave this exercise to others...

Overall it's really not so simple. \since might always help.

Jarek

________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Thiago Macieira <thiago.macieira at intel.com>
Sent: Tuesday, September 24, 2024 11:33 PM
To: development at qt-project.org
Subject: Re: [Development] Proposal to retain \since version information in Qt Documentation

On Tuesday 24 September 2024 14:22:06 GMT-7 Jaroslaw Kobus via Development
wrote:
> > We didn't start adding them until post 4.0. I don't think 3.x had the tag
> > at all and APIs new in 4.0 weren't marked as such either. That means the
> > furthest back we can go is 4.0. Qt 3 to 4 was also a massive update, so I
> > don't think it would be useful to go that far back anyway. Qt 4.0 will be
> > 20 years old next year.
>
> If the change introducing \since were tagged as \since we would now easily
> know when it was introduced.

If you have to do a git blame to find the commit that introduced something, you
don't need the \since. The git tags can tell you where a commit was made part
of.

Two examples. First, prior to the Pick-to existence. Let's say I wanted to
know when QDataStream::Qt_6_0 was added. Git blame says it was commit
543e87c65a8c8a9215c7fa1647792da77c2f6925 authored by you. Qt Creator's commit
view includes:
          origin: 6.0, 6.1, 6.2, ..., 6.8.0, HEAD, dev and 24 more
and in the command-line:
$ git name-rev 543e87c65a8c8a9215c7fa1647792da77c2f6925
543e87c65a8c8a9215c7fa1647792da77c2f6925 tags/v6.0.0-alpha1~3167


Second, after that. Let's say I want to know when QDataStream::NullCode was
added. Git blame says it was added by Øystein in commit
fb81373313c4d1834437351aeb5df4a44303b93c, which Qt Creator says
Precedes: v6.8.0-beta1
Follows: v6.7.0-beta1

But a git show of this commit shows the annotation:
Notes (cherry-picks):
    6.7: 8dd7aba7fd2e6edeee33e97879f7e891028bad7d

And that commit is name-rev'ed to tags/v6.7.0-rc1~141.

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Principal Engineer - Intel DCAI Platform & System Engineering