[Development] RFC: The Future of QDoc
casper.vandonderen at nokia.com
casper.vandonderen at nokia.com
Fri Feb 10 14:15:19 CET 2012
On 2/10/12 8:07 AM, "ext Andre Somers" <andre at familiesomers.nl> wrote:
>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.
Just to reply to the comments in header/enum comments in one go:
Let's first say that I think it would be great to also be able to write
documentation directly in the header.
It can lead to a mess though. We would need some clearly defined
boundaries about where to put documentation. We already have classes where
some of the function documentation is a the top of the cpp file with \fn
(even though they are not defined in the header) and some of the
documentation is next to the functions.
We would also need to reach agreement about how to document enums in
headers, does not having documentation mean that you just want to print
the enum value, and should you explicitly use \omitvalue to not print
I do not know enough about how compilers work (I read some stuff about how
Clang works), but does adding the documentation to the headers not make
compilation slower? Since the file that needs to be loaded by the
preprocessor is bigger? And if that is the case: are we willing as a group
of users that documentation causes builds to be slower? (I don't think we
More information about the Development