Hi, Reviving this for a more specialized case … We have some quite elaborate version information in Qt Quick Controls , like '(since QtQuick.Controls 2.3 (Qt 5.10))’:
https://doc.qt.io/qt-6/qml-qtquick-controls-abstractbutton.html Compared to the original case "\since 4.x” that this thread was about, this does show up in the generated documentation. IMO it is visual clutter and might confuse the users (as with Qt 6 , we got rid of the separate versioning of QML imports that are part of Qt). Also, since it is not a simple version number, the ignoresince QDoc setting can’t be used to hide it. Can we agree that this is OK to be removed? Patch that caused me to write this is https://codereview.qt-project.org/c/qt/qtdeclarative/+/684510 Kai Confidential From: Development <[email protected]> on behalf of Volker Hilsheimer via Development <[email protected]> Date: Wednesday, 25. September 2024 at 11:14 To: Paul Wicking <[email protected]> Cc: [email protected] <[email protected]> Subject: Re: [Development] Proposal to retain since version information in Qt Documentation > On 24 Sep 2024, at 15:12, Paul Wicking via Development > <[email protected]> wrote: > > Proposal: > > 1. Retain Existing `\since` Annotations: I propose that we keep the `\since > [version]` annotations in the documentation, even for older versions like Qt > 4.x, to preserve this valuable information for those who may need it. > > 2. Revert Previously Merged Changes: Consider reverting the changes that have > already been merged, which removed `\since` annotations, to restore the > completeness of our documentation. > > 3. Establish a Clear Documentation Policy: To prevent similar disputes in the > future, we should develop a clear and unambiguous policy regarding the > inclusion of version information in our documentation. This policy would > provide guidance to contributors and maintainers, ensuring consistency and > preserving the integrity of our documentation. +1 to the above proposals. The documentation policy regarding versioning has so far been rather implicit: more experienced reviewers will check that the addition of a new API is not only accompanied by documentation, but that this documentation also includes a \since tag. Looking out for \since is mentioned on https://wiki.qt.io/Things_To_Look_Out_For_In_Reviews#New_Classes, and perhaps it’s quite obvious that one should also look out for \since when reviewing a patch that adds a new API to an existing class. The plan following the respective discussion at Qt CS was to transfer uncontroversial content from TTLOFIR into QUIP(s), although perhaps a more explicit policy on this specific topic might deserve a separate QUIP. If the bot that analyses changes to public headers could learn to look out for documentation (with \since) for changes adding public API, then that could be useful. Volker -- Development mailing list [email protected] https://lists.qt-project.org/listinfo/development
-- Development mailing list [email protected] https://lists.qt-project.org/listinfo/development
