[Development] RFC: The Future of QDoc

[Craig.Scott at csiro.au]

On 10/02/2012, at 5:13 AM, <marius.storm-olsen at nokia.com<mailto:marius.storm-olsen at nokia.com>> <marius.storm-olsen at nokia.com<mailto:marius.storm-olsen at nokia.com>> wrote:

I think there are a few issues here:

1) Only Dimitri touches Doxygen code, and it doesn't look like
contributions go in (at least not under the authors name). This means
that the functionality to support Qt's extensive documentation needs to
be implemented by Dimitri alone. Thus, Nokia's team cannot be working on
enhancing Doxygen to get it up to par with the current output from qdoc.


As someone who has submitted a number of bug reports to the Doxygen project, Dmitri has been pretty good at responding to issues. As you'd expect, the better the quality of your issue description, the better the response. Providing a means to reproduce a problem typically gets a very good response.

Support for other languages has been added over time to Doxygen. I see little reason why something similar couldn't be done for QML. Sure, someone other than Dmitri would probably have to do it, but that's going to be true for qdoc anyway, isn't it? My understanding is that there are some other fairly major contributors to doxygen, but perhaps those people only get a mention in the release emails.


2) From what I've seen of attempts to set up Doxygen, none of them have
proven to create output quality on par with what qdoc produces. This is
obviously due to qdoc only having 1 mission, to produce the
documentation output that the Qt documentation team think is optimal,
while Doxygen is a tool for a multitude of outputs. However, is does
leave a quality gap between the documentation we want verses the
documentation we can get out of the tool. A gap the documentation team
would want to close, which again points to 1).


A counter-argument here is that for those projects that use Doxygen rather than qdoc for their own documentation, it means that you can't incorporate Qt's documentation into your own. This is precisely the case for us, for example. We provide a large Qt-based framework with Doxygen-generated help content. We can't provide links to docs for the Qt classes, etc. because it uses qdoc. We like the Doxygen output and it works well for us, and I suspect there are a lot more projects out there using Doxygen than qdoc. So while qdoc might result in better Qt documentation on its own, does the choice of using qdoc more commonly result in poorer documentation for projects that use Qt?


3) Transforming the documentation in Qt sources to only use current
Doxygen syntax is VERY unlikely, at least in the Qt 5.0 time-frame.


It might be possible to alleviate some of the workload using doxygen aliases to simulate missing qdoc commands.


--
Dr Craig Scott
Computational Software Engineering Team Leader, CSIRO (CMIS)
Melbourne, Australia