[Development] Marking the Tech Preview APIs as such

[Shawn Rutledge]

On Jan 22, 2024, at 10:41 AM, Giuseppe D'Angelo via Development <development at qt-project.org> wrote:

Hi,

A number of classes and functions that are going to be introduced in 6.7 are meant to be "tech preview", and thus they may pass the header review even if we are aware of some limitations or issues with their design.


I propose to introduce a macro, QT_TECH_PREVIEW_API (bikeshed please), that expands to nothing/`[[qt::tech_preview_api]]`/... (moar bikeshed) and it's used to mark APIs that are considered tech preview.

The first goal of this macro is to ensure that making an API officially supported (and out of TP) will require changing the header, and therefore be picked up in the next round of header reviews.

Otherwise, there is the chance that an API becomes official by simply adjusting the documentation, and one may not notice that this has happened during the next API review (and confirm that all the shortcomings have been addressed).


The second goal would be for qdoc to automatically document methods and classes marked by the macro as TP.

We have the qdoc \preliminary tag.  But we haven’t always used it consistently; some docs just have a \note instead.  https://doc.qt.io/qt-6/16-qdoc-commands-status.html#preliminary If a whole class is considered to be Tech Preview, it’s easier to add one note than to mark every function as preliminary.  In the case of the TextDocument API, it was exposed only for C++ API before (as a middleman to provide access to the QTextDocument that a TextEdit is using), and now it’s gaining properties and invokables, so effectively the whole class is Tech Preview from a QML-API perspective.

I guess your goal is to be able to see it in the header rather than having to look up the docs in the cpp file or online?  (Alternatively we could write all docs in headers, but then the headers get to be large, take storage space alongside every installation of Qt binaries, and slow down everyone’s compilations, so I guess that’s why we don’t do it that way?  Or we could somehow include doc diffs in API review patches for whatever API the script has already decided is “interesting".)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240122/3b20154b/attachment.htm>