Using qdoc to document classes within a namespace

[david1811]

Hello,

I try to use qdoc to document a class which is within a namespace, and have the following problems:
(just a preliminary remark: in my setup, everything works fine if I remove all the namespaces; I use qdoc in qt beta5 under osX).

for example, I have a class Feature in a namespace xxx:
@
namespace xxx {
class Feature {
...
}
}
@
I try to write a documentation for it:
scenario 1:
the class is a pure header class, thus I write a Feature.qdoc file, and add the following comment:
@
/*!
\class Feature
...
*/
@
I get the error
Cannot find 'Feature' specified with '\class' in any header file
if I add 'using namespace xxx;' in the first line of the .qdoc file, nothing changes.

Now, instead of using a .qdoc file, I use a .cpp file. The error disappears if I add 'using namespace xxx;'; still, if I refer to the class using \l{Feature} somewhere else, I get the error: Can't create link to 'Feature'

scenario 2:
same as above, but I link to the class using \l{xxx::Feature}. When running qdoc, it does not complain, but using the documentation, and clicking on the link, it tries to open a file named xxx-feature.html, which qdoc did not create (it does not exist).

scenario 3:
I use \class xxx::Feature instead of \class Feature in the source file, but the xxx-feature.html does not get generated.

I googled quite some time, and did not find any answer. Is there a solution ? the only one I found was to remove the namespace, or to replace it with a macro which I add to the Cpp.ignoretokens (but for some reasons, this is not a good solution in my case)

what are the best practices to document code with namespaces ??

thanks, Dd

[David Stiel]

Hi,

It looks like the html output files (xxx-feature.html) are only generated if you describe the namespace (eg. in a separate .qdoc file):

/*!
\namespace publish

bla bla bla

*/

On a side note documentation of properties (\property ) only works if the Q_PROPERTY(...) declarations comes before any Q_ENUMS(...)

[sierdzio]

If you are not working on Qt itself, it's recommended to use Doxygen instead of qdoc. Just sayin' ;)

[David Stiel]

Out of curiosity. Why do you recommended doxygen instead of qdoc. I was kind of intrigued by using the qdoc because it comes with Qt and can document Qt stuff like properties, signal, slots etc. But I’m sure you have your reasons… ;)

[JKSH]

QDoc is an internal Qt tool. It's possible to use it for external projects, but I'm not sure if it was intended for this purpose.

Doxygen, on the other hand, was specifically designed to be used by external projects. It "understands Qt features":http://www.stack.nl/~dimitri/doxygen/manual/features.html like signals and slots.

[sierdzio]

As JKSH said, plus:

• qdoc does not guarantee it's API, it is being modified between Qt releases and can simply break without notice
• doxygen supports just soo much more: aparat from C++ and Qt with all it's features (including QML), it also understands Java, JavaScript and many others. It also supports different comment styles, and can produce much more output formats than qdoc (HTML, PDF, man pages, LaTeX, etc.)