[Development] Marking the Tech Preview APIs as such

[Volker Hilsheimer]

> On 22 Jan 2024, at 22:15, Giuseppe D'Angelo via Development <development at qt-project.org> wrote:
> 
> Il 22/01/24 19:03, Shawn Rutledge via Development ha scritto:
>> 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".)
> 
> As I said, it's not just in order to see the tag in the header when the code is introduced, but also to see that a TP class is getting out of TP status because the tags are being removed (= the header is being touched, and will appear in the header review). If \preliminary is removed from the docs, it won't be obvious at API review time.
> 
> My 2 c,
> -- 
> Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer


I like this proposal; having it visible in the header that an API is either new as, or still in, or moving out of tech preview is very useful information for the header review process.

A QT_TECH_PREVIEW_API macro that expands to “whatever works” works for me. It can expand to nothing for the purpose of header review, but if we can make it an attribute that qdoc can use to implicitly add the relevant boilerplate to the respective reference documentation, then it removes the need to keep \preliminary documentation tagging in sync.

I also like the general idea of supporting the header review process with more information, such as links to the relevant documentation, or even a documentation diff, or even change on gerrit that introduced the change; but that’s probably orders of magnitude harder and complex to implement, so let’s not wait for that.

Moving documentation into the headers is a no-go for me, not only because of the overwhelming amount of status quo. Documentation needs to inform the user about what the API does (or, well, is supposed to do), and might need to change when the implementation does. This is less likely to happen when it lives next to the declaration.

Volker