[Development] qdoc for C++ and QML

[Martin Smith]

>Maybe qdoc could look for qmlRegisterType etc. in the cpp files and discover
>those relationships without writing anything else?  It has a better parser these
>days, right?

It certainly does have a better parser, but for speed, we tell it not to parse the code blocks. Only declarations and signatures.

>Otherwise if you really need a separate qdoc comment, maybe make it look
>kindof like the QML registration.

It doesn't need a separate comment, just something in the one common comment that indicates the class is both C++ and QML.
________________________________________
From: Shawn Rutledge
Sent: Monday, April 24, 2017 5:08:25 PM
To: Martin Smith
Cc: development at qt-project.org
Subject: Re: [Development] qdoc for C++ and QML

> On 24 Apr 2017, at 16:38, Martin Smith <Martin.Smith at qt.io> wrote:
>
> The problem when combining C++ and QML documentation is qdoc has no way of knowing whether a QML type exists for a C++ class or whether a C++ class exists for a QML type.
>
> Should we add a new command like \cpp-qml to indicate that both exist and are documented the same?

Maybe qdoc could look for qmlRegisterType etc. in the cpp files and discover those relationships without writing anything else?  It has a better parser these days, right?

Otherwise if you really need a separate qdoc comment, maybe make it look kindof like the QML registration.

\qmltype QQuickMyClass MyClass 1.0

or just

\qmltype MyClass

because qdoc already knows which C++ class the comment goes with, and hopefully can get the version from other comments too.  But it amounts to repeating oneself in the code, which is always annoying.

> And if a C++ class has a corresponding QML type, should every member function be included in the documentation for both? How will qdoc know that a member function only applies to the C++ class or only to the QML type?

Q_INVOKABLE for methods should cover it, I think, if qdoc already knows that the class is exposed to QML.  Plus properties, of course.  Usually a property setter is not invokable, but there can be exceptions.



I guess we haven’t run into this very frequently yet because so few classes have both a C++ and a QML API within the same class.  Many QtQuick classes have no public C++ API (so we only document the QML API), and some are wrappers around legacy classes that have different C++ API, or classes for which we know the C++ is too complex or inappropriate to expose directly to QML.

Some people even seem to think that as a rule of thumb, C++ and QML APIs should be in separate classes (in other words always write a wrapper for QML), just in case we later need the two APIs to diverge… but I’m not a fan of boilerplate wrapper code and needless indirection.  Especially when it can’t be compiled out of existence, and thus bloats the memory footprint and slows down execution.  Especially if both the real object and its wrapper are QObjects.  But if you put both in the same class, you always have to be careful, keep in mind that adding C++ API might add QML API too, if it’s either invokable or a property.  (We got in trouble with Window, but that has a worse problem: inheriting from the wrong class in the first place.)  And we do try to keep QML APIs as slim and harmless as possible (in case a graphical design person ends up using them).

At least QQuickItem rightly has both public C++ and QML API in the same class, and I don’t suppose anybody thinks we should have avoided it in that case?

If qdoc auto-discovers the QML API that goes along with the C++ API, not only will we ensure that it’s all documented, but it may help anyone who is changing the C++ API to verify that the QML API changes which come along with that are really intended, and suitable for QML API.