[Development] RFC: The Future of QDoc

[Andre Somers]

Op 9-2-2012 19:13, marius.storm-olsen at nokia.com schreef:
> 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.
That only goes for code that is actually *in* the cpp files. It does not 
hold for enums, flags, inline functions and typedefs, nor does it hold 
for the many cases where the code is actually in a private class and the 
implementation contains little more than a d->doSomething().
I'm not saying that putting all documentation in the header file is 
better, but it would IMHO be better if we were able to put the 
documentation at a place were we do not need to repeat ourselves. As you 
say: that makes it less likely to be properly updated. That results in 
being able to parse both the headers *and* the sources.

For the rest, you make excellent points. If doxygen really is that 
"closed", and it is currently not up to par with what Qt needs, then we 
need to stick with qdoc. However, the general idea to use what is out 
there instead of trying to maintain every part of the toolchain 
ourselves does appeal to me in general.

André