[Development] RFC: The Future of QDoc

[André Somers]

Op 2/10/2012 2:15 PM, casper.vandonderen at nokia.com schreef:
> 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.
>>
>> André
> 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
> anything?
My suggestion would be this:
1) If possible, documentation goes right above the relevant code 
(implementation or declaration)
2) Prefer the implementation over the declaration when you have to choose
3) If neither is possible, prefer the implementation file to put your 
artificial \fn's and the likes

Personally, I think that the workflow that you need to *explicitly* 
document everything is good. No need to change that. So if an enum is 
not documented, it is not in the documentation. A warning must be issued 
in the output for building the docs though.

> 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
> do)
In principle, I think you are right, but the same goes for *any* comment 
in the code. In principle, they make the compiler a bit slower due to 
having to load and parse bigger files. However, quality of documentation 
is IMHO way more imporant, and I doubt the difference would be 
significant, especially if you limit the use of headers for 
documentation to the cases I mentioned above: only those things (enums, 
typedefs, template methods or classes) that do not have an 
implementation in an implementation file. What will take more time 
though, is building the actual docs, as qdoc would have to scan not only 
.cpp but also .h files.

André