[Development] RFC: The Future of QDoc

Olivier Goffart olivier at woboq.com
Fri Feb 10 10:20:25 CET 2012


On Friday 10 February 2012 08:07:07 Andre Somers 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.
 

And... other libraries put their documentation in the headers, because the 
source code is usually not installed so user can look it up easier. 
Also, the IDE already parse the header, so they can easily parse the 
documentation in order to show it usefull place (kdevelop does that very well)


Anyway, choosing between .cpp or .h is not the question here. 
It is about the same as tab vs. space, or camel case vs. underscore.
Doxygen support everything AFAIK.

Qt has historically always wanted to use their own solutions for everything. 
(Leading often to inferior choice IMHO)




More information about the Development mailing list