[Development] RFC: The Future of QDoc

[casper.vandonderen at nokia.com]

On 2/13/12 1:00 AM, "ext Craig.Scott at csiro.au" <Craig.Scott at csiro.au>
wrote:

>
>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.
>

Providing a bug report is something different from providing patches that
add new functionality. (as seen with Qt before open-governance)

>
>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?
>

I am just reading the Doxygen manual, and it says: "Another case where you
should use doxytag is if you want to create a tag file for the Qt
documentation.". Would it not be an option to extend qdoc to output a
correct tag file, which Doxygen can understand? (assuming we keep qdoc).


Whatever is chosen (updating qdoc, or changing to Doxygen): The task is
not small, and therefore it would be nice if there would be more
contributors than just me and Martin Smith. Maybe it would be a good idea
to have a sit-down at the Contributors Summit (if people are interested).


Casper