[Development] RFC: The Future of QDoc

[casper.vandonderen at nokia.com]

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

Just to add what I think to Marius' comments:
1. Doxygen would need some extra features, the major one being QML, but also being able to use index files to easily link for instance the Creator docs to the Qt docs.

2. Even if we would use Doxygen we would still need a fork before a release, I do not think we can line up releases of Doxygen with releases of Qt. And having a Doxygen version number like 1.7.6.2-qt-SHA1 also doesn't look too great.

I would personally not mind using Doxygen, but I do agree with the points about Dimitri only changing the code and the quality of Doxygen output (which you can of course change)

Casper