[Development] RFC: The Future of QDoc

marius.storm-olsen at nokia.com marius.storm-olsen at nokia.com
Thu Feb 9 19:13:54 CET 2012


On 09/02/2012 10:33, ext Manuel Nickschas wrote:
> On Thursday 09 February 2012 15:36:09 ext Olivier Goffart wrote:
>>> I am working on QDoc part-time and we have been discussing some
>>> changes that we would like to implement to make qdoc more future
>>> proof. I have created a short list of the things we would like to
>>> do: http://developer.qt.nokia.com/wiki/Category:Tools::QDoc
>>>
>>> It comes down to: Implement a new C++ parser, make qdoc more
>>> modular and be able to handle the Qt modules better with qdoc.
>>>
>>> I am wondering if anybody has any ideas about what he/she would
>>> like qdoc to do, or how qdoc should evolve?
>>
>> Have you thought about using doxygen or any similar tool?
>
> Or at least make QDoc be able to parse doxygen-style comments (which
> also means it should not ignore headers, as documenting public API
> in a header file is much more common at least outside Qt than doing
> that in the implementation file...)

Qt puts the documentation in the sources since it's closer to the actual 
code, and thus more likely to be maintained at the same time as the code 
is changed. If the documentation is in another location, it's far more 
likely to be "forgotten" when updates/changes to behavior is done in the 
source code.


> I'd be happy to see Qt use or at least support more standard
> solutions over homegrown ones. Since that failed for localization,
> maybe we can at least get it for documentation :)

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.

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

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.

All of the above is my personal opinion of course, and *NOT* 
representative of the Qt Documentation team, qdoc team or any other team 
in Nokia. I like Doxygen, and have used it on several occasions for my 
own personal projects; but I still feel that the output of qdoc looks 
better.

(And no, I *don't* use the inheritance charts. I think they are 
pointless, and not nice to look at. If you need them, something is 
obviously too complex in your design.)

-- 
.marius


More information about the Development mailing list