On Jan 22, 2024, at 10:41 AM, Giuseppe D'Angelo via Development 
<development@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".)

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Reply via email to