QDoc in QML files issues

[feldifux]

Hi,
after working a while with qdoc-comments inside qml files, I had a couple of issues...

First, documentation for functions is not generated. So if you have the following qml code:
@
/*!
This documentation should be exported.
*/
function myFunc() {
}
@

... then no documentation is exported (I use HTML for output).

Similar to this missing support of function documentation, also signal documentation infos are not exported.

In addition, also the \internal command of qdoc is ignored. So if any property should not be exported (by using the \internal command) it is still visible in the exported HTML file! Here is an example:
@
/*!
\internal
This property documentation should not be exported, but it is!
*/
property int testProp
@

I did try these scenarios with qdoc3 from Qt version 4.8.1, 4.8.2 and also Qt5 (the current master). With Qt5 even normal property documentations do not get exported, so it is the least working version.

The exporting works fine, if I write the documentation in a separate .qdoc file. However, I do not like the approach of separated doc/source code as you will always miss something when they are not in the same place (so not in one qml file), and they get easily out of sync. In the QtQuickComponents for Symbian & Meego project the doc is written in separate files, but I guess generating docs from qml files is supposed to work, because it even is documented in the qdoc3 manual: http://doc-snapshot.qt-project.org/qdoc/componentset.html

I hope anybody has experience with this issue and could help me out.

cheers,
Chris

[feldifux]

Hi again,
I figured it out - with Qt5's qdoc my mentioned issues were fixed (I had an old version of qt5 still using qdoc3).

So now everything works as expected and documented in the manuals, and docs can be exported without extra topic commands like \qmlmethod or \internal.

I can now highly recommend qdoc! We use qdoc for the documentation of our Qt-based 2D game engine for QML and C++ code, which works pretty well because you can export the docs for the integrated help in QtCreator AND to web templates (see here how ours looks like: http://doc.v-play.net/beta/).