QDOC3 for Qt-based application
-
Hy to all, I've a question, Qt developer recommend Doxygen to generate documentation instead of qdoc3, why is it?
qdoc3 Readme.txt:
"
qdoc3 is the tool used to generate the Qt reference documentation.
The source code is included as part of this package primarily to
fulfill our GPL obligations. We highly recommend using
Doxygen ("http://www.stack.nl/~dimitri/doxygen/":http://www.stack.nl/~dimitri/doxygen/) for generating
documentation for your Qt-based application.
"Sorry for my English...
Regards
Antonio[edit: fixed link / chetankjain]
-
Doxygen is more common tool. Also qdoc3 is only for internal use for qt and creator documentation.
-
Thanks Denis for your answer.
I'd like learning qdoc3 but I've problems with project files (.pro and .pri) configurations.
I know and use Doxygen but I'd prefer generate documentation with Qt tool, in this manner it isn't required to install an other application. -
Doxygen is also more generic tool.
There doesn't seem to be virtually any manual for qdoc3, so I suppose it has some Qt-only quirks that can go causing problems with generic projects. Doxygen has originally written for Qt, and it supports it well.
Despite the default outlook of Doxygen is ugly and not convenient, there is theming options one can use to create proper documentation.
This is my personal opinion, but I'd like to use qdoc3, if it allows using Qt's doc usability functionality out of box. Those are just so nice parts that every doc should have them.
-
Here is the "qdoc manual":http://doc.qt.nokia.com/qdoc/
I found the link in the wiki "WritingQtDocumentation":http://developer.qt.nokia.com/wiki/WritingQtDocumentation -
The thing about qdoc3 is that it is subject to change.
With Jambi I’ve been forced to mess with qdoc3 and found that features used for Jambi doc generation is not in that documentation. Maybe there is more unknown features? It’s hard to know from version to version how well it will play this time...
If I ever get around to study qdoc3 a bit more, I may even write a guide how to actually is it for your own project, with those features. Simple generation is quite easy though, just build qdocconf file that specifies stuff about your source,
http://doc.qt.nokia.com/qdoc/25-qdoc-configuration-derivedprojects.html describes it quite well.Most confusing thing about qdoc3 for me has been its usage of environment variables, I prefer to pass stuff using flags or conf files to binaries ( I don’t even have bash, so bash stuff apply to me; I usually use env or scripts)
-
Doxygen also can now create qhp files, and was actually written as a qdoc clone which wasn't tied to Qt. It's one of the main tools used for documentation in many, many projects.
If you write to qdoc3, you're basically stuck with the very limited information in the Qt docs (and of course whatever you can glean between here, qt-interest, and #qt), whereas if you are using Doxygen, there is a big manual and a big community using it.