[Development] QML API Review

[Kai Koehne]

Hi,

In addition to the C++ API review that Edward has been pushing, we also need to review new/changed QML API.

Most of our QML API is actually defined in C++, so one way to review them is diffing the corresponding .h files; however, because they are private (in the C++ sense), every module is free to place these files in different locations. It also misses the information on how exactly the type is registered in the end (think of qmlRegisterXXX).

Fortunately, we have another way to inspect QML API: The plugins.qmltypes files that every plugin is supposed to ship alongside. The prime use of these files is to make syntax highlighting and code completion in Qt Creator possible. However, it turns out it's also a very concise way of reviewing new API, so let's use it for that 😊.

The .qmltypes files need to be updated manually. I've now run the update for all the .qmltypes files I could find and upload the change for review (see also https://bugreports.qt.io/browse/QTBUG-70264 and linked patches). I suggest to use these patches as the basis for reviewing the QML API. Different from C++, I suggest that if you're happy with the API, please +2 it - The patch will actually be merged in the end.

Note that some the plugins.qmltypes files got updated in between, and therefore the patches do not show the full diff to version 5.11. Other plugins.qmltypes files didn't see an update in 5.11, something we should really avoid in the future ☹ In these cases a separate review might be necessary.

Anyhow, it turns out that most developers don't update the plugins.qmltypes files, so I suggest to establish this as the new norm, and update them only before the release, as part of the API review process.

An alternative would be to make sure that the .qmltypes files are up to date directly before the API review, and include them as part of the C++ diff. Anyhow, this would require us to _not_ instantly fix things in the .qmltypes file when it gets updated, but first check in the plugins.qmltypes file as is - something that can be difficult to accept. So maybe it's just easier to have this as separate diffs.

Regards

Kai

PS: I intend to codify this http://quips-qt-io.herokuapp.com/quip-0010-API-review.html , but first wanted to establish a consensus.

--
Kai Koehne, Senior Manager R&D | The Qt Company

The Qt Company GmbH, Rudower Chaussee 13, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Mika Harjuaho. Sitz der
Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, 
HRB 144331 B

The Future is Written with Qt
www.qtworldsummit.com