> On 24 Sep 2024, at 22:37, Axel Spoerl via Development 
> <development@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
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Reply via email to