Convert Doxygen comments to QDoc comments

[bguivarch]

Hello,

I am trying to convert Doxygen comments to QDoc comments, but I am facing some troubles.
For example, I looked at the Command Index but can't find matching commands for Doxygen's @author and @date tags.

How do you do this with QDoc?

Regards

[SGaist]

Hi,

A quick look at the code of qdoc shows that there is a author and releasedate tag.

Hope it helps

[bguivarch]

Hello,

Thanks for your answer. Nonetheless, I have decided to go back to Doxygen because as far as I understood, to generate qdoc you have to provide HTML templates to tell him how to generates the pages. And I don't have time for that. Too bad there is not already an HTML template provided with qdoc.

Regards

[SGaist]

Do you mean these html elements ?

[bguivarch]

Hello,

Well...I guess I have to put these HTML variables in my .qdocconf file and bam magic!
In my defense the documentation is a bit unclear as the example file doesn't contain these HTML details.
I will give a second try to Qdoc, then!

Regards

[SGaist]

It would likely be an interesting addition.

Please go to the bug report system and open a feature request for the documentation to improve that page.

[NameRakes]

Hi SGaist, I am new to Qt, but (hopefully) learning fast! I really like the clean look of Qt-style documentation, that is QDoc (correct me if I am wrong). I am also interested in generating QDoc style presentation instead of doxygen produced output. I have already done quite a bit of doxygen style documentation in my code.

I have quickly read the QDoc manual, but it is not clear to me if I have to rewrite my comments into CPP files? Do you have a specific example for the process of converting an existing code base with doxygen style comments in H/HPP files and generate QDoc style documentation? Any pointer is greatly appreciated.

[NameRakes]

Hi @SGaist I tried to execute qdoc.exe in the command line window with a sample .qdoc file for a class. I created .qdocconf as explained in the QDoc documentation. The first line of the config file is supposed to be include(compat.qdocconfig) as explained in the minimum required qdocconfig file section. The the program tried to open "include(compat.qdocconf)" as a FILE! So I removed include and provided directly the compat.qdcoconf as the first line in my .qdcoconf file and then reran the program.

Now qDoc.exe has eaten all my source code! No kidding, and my svn is not working. I am trying to restore my checkout from the repo. I hope I can get back my source code checked out.

I have no idea what is going on. Please let me know what is my recourse here? Thanks.

[NameRakes]

Ok, this is really bad. Most of my disk has been wiped out. I was running qdoc.exe, it took a while, so when I realized something was wrong, I killed it. By then the damage was done.
My CMake, Qt, including Microsoft installations have been wiped out. Although one can be never sure, it happened with the execution of qdoc.exe as explained in the Getting Started with QDoc chapter.

Luckily I was able to install svn and get back the source code from repo as of this afternoon. But I have lost some data that I didn't have on the cloud. Don't know how long ago was the back up.

This is NOT good news!

[SGaist]

There's something else that's going funky.

qdoc opens source files in ReadOnly mode.

Can you show your setup files ?

What version of Qt are you using ?

[NameRakes]

@SGaist I am working on it. Hopefully, It is not related to QDoc. Will get back to you.

[NameRakes]

Ok, I am almost certain it is the avast anti-virus program, and not qdoc. Other people have reported similar problems. Was running qdoc and avast at the same time, noticed something strange, and luckily stopped it.

It ate up the entire Qt installation tree, my source code and a bunch of apps (office, latex, cmake, ...). Was able to restore the apps and the source code from the repo (luckily had committed only that afternoon). But I did loose some data, some small prototype codes that I don't check-in to the repo.

My own Qt-based app is running fine, but the strange thing is my doxygen output is messed up. I see only File entries, no namespace::class level descriptions.

Wonder if qdoc interferes with doxygen generation? Do you think that's even possible?!

[SGaist]

Anti-virus can be nasty with developers...

What do you mean by your doxygen output ? The help files generated by qdoc ?

[VRonin]

Probably useless contribution:

QDoc and Doxygen are not 2 different products, Doxygen is in fact a fork of QDoc. Since Doxygen is now so common in the C++ world, it ended up being supported more than the parent project (QDoc).
You can generate qdoc files with doxygen and if you want them to look like normal Qt5 documentation you just need to change the CSS (a good place to start is https://github.com/fenderle/doxygen-qtify )

[NameRakes]

Yes, I realize that QDoc and Doxygen are two different programs. Doxygen's help doc collection (in html) usually has a namespace tree, a class list, and a file list. Now I see only the file list. No actual documentation, just code listed for each file. I have to dig into why doxygen got messed up.

@VRonin your pointer is extremely valuable to me - the link to qtifying doxygen. That's exactly what I was looking for originally. But first I need to reinstate my doxygen output.

[NameRakes]

I managed to restore doxygen output. I tried this qtify.css - it does not have what I am looking for: Qt-style table of contents in each page at the right top corner + when the signature of a member function with many arguments is shown, Qt-style tries to do it all in 1 line unlike doxygen which puts 1 arg per line in the html output.

I think that the TOC at right top corner comes from MD tags, but don't know how to combine that with the rest of the page in html. I hope css would allow this possibility. Will do more research. If I find it, will post. If you know, and can point me to a link that'd be great.

Thanks, as usual, for all the help.