Hello all, We, the doc team, would like to implement a change to how we document QML types in QDoc. Currently, QDoc assumes things about the \qmlclass command that causes errors or misinforms about the true nature of the QML type.
Example usage: "\qmlclass Item QQuickItem" For example, we advise that QML types have two arguments to the \qmlclass, one for the type name, and the other is for the C++ class implementation. For several cases, the second argument is not needed. This causes ambiguity about the intention of author and the necessity of the second argument. In practice, QDoc uses the second argument to check the C++ documentation for properties. Cases for different QML types: a)there is a C++ class, so the second argument is needed b)there is no C++ class, so the second argument is not needed (for example, components) c)there is a C++ class, but may or may not have a second argument Our proposal is to: 1)rename "\qmlclass" to "\qmltype" 2)add a command called "\instantiates" with the C++ class the argument Proposal 1 addresses the terminology inconsistencies. We decided on "QML type" as the official term before and never implemented it in QDoc. Proposal 2 makes the C++ class information as a "context command", adding additional information to the QML type documentation. Other context commands include \since, \inherits, and so on. We settled on a context command as we can avoid the ambiguity by explicitly tagging the QML type as a type that is implemented by a C++ class. Another argument is that it reduces the logic behind qmlclass, reducing bugs and confusing errors. Examples: \qmltype Item \instantiates QQuickItem \qmltype Button Of course, we will go through the documentation and change them ourselves. **We will do the changes to the documentation and the manual, so you don't have to.** Tasks for the doc team: -implement change in QDoc, but gracefully deprecate the \qmlclass by giving a warning about using \instantiates instead. -go through the modules and change the documentation. Notify the maintainer. -send email to the affected maintainers. Cheers, Jerome P.
_______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development