-
Epic
-
Resolution: Unresolved
-
P2: Important
-
None
-
None
-
qtquickcleandoc
For the general use-case of QML/QtQuick technologies with other languages, it's required that the documentation can be written in a way that people can get a good understanding without having to know details for a specific programming language.
One example is the current Qt Quick documentation https://doc.qt.io/qt-6/qtquick-index.html that mentions the C++ API. (similarly with Qt QML https://doc.qt.io/qt-6/qtqml-index.html )
The goal is for people to learn QML/QtQuick without the need of knowing C+{}{}, so this can enable projects like Qt Bridges to refer to those docs, without requiring users to be familiar with C+ details.
On the other hand, we need to be careful that existing documentation targeting Qt/C++ developers can still be found, especially the parts which are relevant for deep integration. Consequently, we need to consider a few cases:
- There should be a C++ free introduction to QML/QtQuick – with some additional focus on Controls, not on pure QtQuick. We might want to take some inspiration from the QtQuick learning path from https://academy.qt.io
- We need to keep our reference documentation for QML types intact; but it should become usable without C++ knowledge.
- We should ensure that properties and method types are exposed as actual QML constructs. https://doc.qt.io/qt-6/qml-qtquick-controls-verticalheaderview.html#model-prop should e.g. specify its type as "var", not as "QVariant", https://doc.qt.io/qt-6/qml-qtquick-window.html#sceneGraphError-signal should use string instead of QString, and have some documentation for SceneGraphError.
It should be possible to systematically find instances of this by checking the qdoc log for missing references - Notably, enums should ideally not only be documented as "enum", or even worse, as "int". Instead, qdoc should ideally create a table from the existing C++ documentation, but native to QML (like https://doc.qt.io/qt-6/qml-qtquick-item.html#focusPolicy-prop). If that can't be done via qdoc, it should be done manually.
- Some sections are referring to C++ documentation for more advanced use cases, e.g. https://doc.qt.io/qt-6/qml-qtquick-image.html refers to QQuickImageProvider. Ideally, we can hide those sections when the documentation is accessed in a bridges context. From a maintenance point of view, we should avoid duplicating the content without C++ references, and instead focus on hiding parts, as otherwise the documentation will quickly be out of sync.
- We should ensure that properties and method types are exposed as actual QML constructs. https://doc.qt.io/qt-6/qml-qtquick-controls-verticalheaderview.html#model-prop should e.g. specify its type as "var", not as "QVariant", https://doc.qt.io/qt-6/qml-qtquick-window.html#sceneGraphError-signal should use string instead of QString, and have some documentation for SceneGraphError.