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

[Paul Wicking]

> On 24 Sep 2024, at 22:37, Axel Spoerl via Development <development at qt-project.org> wrote:
> 
> Some thoughts to add:
> 
> - I can’t seem to find any pattern / rules as to when a \since tag was added in the past. Some APIs have a \since 4.x tag, some have nothing at all. Putting effort into regulating the removal of something, that has been added in an unregulated way, is totally OK if it’s a priority.
> 
> - As Christian said: The beauty is hidden in the official part of the documentation.
> 
> - It’s of course visible in cpp files. If I have my hands on C++, I tend to believe more in git blame’s version of the gospel.
> 
> I don’t feel strong for either side.
> I really welcome the discussion!
> I have approved removal commits in the past, based on the considerations mentioned above. Totally happy to revert those, if that’ll be the consensus.

Hi Axel,

I appreciate your point about the inconsistency in how `\since` tags have been
added over the years. This inconsistency makes it challenging to rely solely on
these tags for historical information. Your observation highlights the need for
a more regulated approach moving forward, which I hope can be informed by the
current discussion.

Regarding your point about the "beauty being hidden in the official part of the
documentation," I agree that the primary value lies in the official, published
documentation that developers commonly refer to. I still maintain that the
`\since` annotations, even if not prominently displayed, serve as valuable
metadata within the source code. They can aid developers who delve into the
codebase and can be leveraged to enhance the generated documentation when
needed.

As long as the `\since` lines are kept intact, we can "unhide the beauty" with a
trivial one-line change to a config file. If we drop them, that option goes away.

//! Paul