[Development] Change of QDoc command from \qmlclass to \qmltype

[jerome.pasion at nokia.com]

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120724/c54b448b/attachment.html>