Qdoc, Doxygen and QML types implemented with C++

[tdunn]

I want to document QML types that are implemented with C++. What is the best way to do that?

For example, I implement a QML type called MyQmlType with a C++ class called MyQmlTypeImpl.

I am experimenting with using QDoc rather that Doxygen for documenting QML types that we have implemented using C++. I am doing this because our attempt to leverage Doxygen for documenting QML types has not been satisfactory. The output does not look like pure QML doc. Some things look like C++, such as the scope operators.

I have read several postings in this forum (see below) advising not to use QDoc unless we are writing something to include into Qt itself.

Okay, fair enough. But, what got me interested in using QDoc is that it allows me to use commands like \qmltype in the C++ source file to create nice QML-esque doc.
/*!
\qmltype MyQmlType
\instantiates MyQmlTypeImplInCpp
\ingroup MyGroup
\inqmlmodule MayQmlModule
\brief Brief description
. . .

This works, but only sort of. I am running into some of the problems mentioned in the forum postings mentioned below, such as namespaces preventing QDoc from finding class references in header files.

To clarify, I do not want to do what doxqml says it does in its doc: "Doxyqml turns .qml into pseudo-C++ which Doxygen can then use to generate documentation." I am not documenting QML code. I am documenting a QML type implemented with C++ code.

Any suggestions are appreciated. Thanks.

See also:
https://forum.qt.io/topic/33856/exclude-qt-class-from-my-own-class-list-in-qdoc
https://forum.qt.io/topic/20383/using-qdoc-to-document-classes-within-a-namespace/6
https://forum.qt.io/topic/31090/what-s-the-benefit-to-use-qdoc-than-doxygen/7

[tdunn]

I had a good conversation with Qt technical support over the past couple of days. This conversation is continuing.

I was encouraged to find out that QDoc is fully supported for writing documentation for projects that use Qt but are outside the Qt project. Here is what I was told by a technical support engineer.

QDoc is a tool used to generate documentation for Qt based software projects. I would not say that you can’t use it unless you’re writing something to include into Qt itself; QDoc is a good tool for you if you’re creating documentation for a Qt project. QDoc works by extracting QDoc comments from project source files and then formatting these comments as HTML pages or DITA XML documents. QDoc checks for QDoc comments in .cpp files and in .qdoc files. Thus you won’t get pseudo-C++ like with Doxygen.

When it comes to the namespace issues, you should be able to overcome this by defining in the QDoc configuration file that the namespace expression is ignored. You can do this with the Cpp.ignoretokens variable. For more details please see:
http://doc.qt.io/qt-5/21-0-qdoc-configuration.html
http://doc.qt.io/qt-5/23-qdoc-configuration-cppvariables.html#cpp-ignoretokens-variable

As an example you could take the Qt Charts Add-On module to see how QML types implemented with C++ are documented. There in the QDoc configuration file the namespace for Qt Charts is added to the Cpp.ignoretokens variable. You can find the file under: %QTDIR%l\EnterpriseAddOns\Charts\2.0\Src\src\charts\doc. Then, for example, for ChartView the implementation is in declarativechart.cpp (%QTDIR%\EnterpriseAddOns\Charts\2.0\Src\src\chartsqml2\declarativechart.cpp) as well as the documentation for the QML type.

From my perspective QDoc is a good tool to create the documentation. I hope the above instructions help you to create the documentation for your project with QDoc.

When I asked about long term support, I got this response.

QDoc is a tool we ship with Qt and it’s something we support. Bugs related to QDoc can be reported and they are addressed as with any other component we ship. As a matter of fact you can find issues reported to it by ‘Build tools: qdoc’ component: https://bugreports.qt.io/browse/QTBUG/component/20323.

All Qt documentation is done with QDoc and we don’t have any plans to change that so QDoc should be around for at least several releases. I wouldn’t be too worried about it suddenly being unsupported.

So, many thanks to Qt technical support. We plan to go ahead with using QDoc for documenting our own Qt-based software.

[sierdzio]

Thank you for sharing this info