[Development] RFC: The Future of QDoc

[Manuel Nickschas]

On Thursday 09 February 2012 19:13:54 Storm-Olsen Marius (Nokia-MP/Austin) 
wrote:

> > 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.

Well, I'm not advocating changing the doc location for Qt itself. But if QDoc 
supported to also have it in headers, Qt-using projects at least could use the 
common way of documenting the headers (this makes especially sense for 
libraries, where header files often are all you have available when having 
them installed on a system).

> > 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 :)
> 
> I think there are a few issues here:
> 
> 1) Only Dimitri touches Doxygen code, and it doesn't look like
> contributions go in (at least not under the authors name). This means
> that the functionality to support Qt's extensive documentation needs to
> be implemented by Dimitri alone. Thus, Nokia's team cannot be working on
> enhancing Doxygen to get it up to par with the current output from qdoc.

Ok.

> 2) From what I've seen of attempts to set up Doxygen, none of them have
> proven to create output quality on par with what qdoc produces. This is
> obviously due to qdoc only having 1 mission, to produce the
> documentation output that the Qt documentation team think is optimal,
> while Doxygen is a tool for a multitude of outputs. However, is does
> leave a quality gap between the documentation we want verses the
> documentation we can get out of the tool. A gap the documentation team
> would want to close, which again points to 1).
> 
> 3) Transforming the documentation in Qt sources to only use current
> Doxygen syntax is VERY unlikely, at least in the Qt 5.0 time-frame.

Ok, so I QDoc seems to be more powerful than Doxygen. I can understand that.

However, it would be nice to be able to use Doxygen-style comments with QDoc. 
I am not too familiar with the QDoc format yet, but it seems it misses some 
nice convenience features like being able to document things directly where 
they are declared. For example, I can document enum members directly in the 
header, and don't need to define a block somewhere in the .cpp where I need to 
explicitly enumerate the members again. I can document a function where it's 
declared, without adding an explicit \fn somewhere else, and so on. It's just 
cumbersome to work with that, in my opinion, unless I've missed something...

So I guess what I'm really advocating is to add Doxygen parsing to QDoc, in 
order to allow using QDoc for projects that already have Doxygen comments in 
place, or to make the barrier of entry easier for developers that have a 
Doxygen background. 

Of course that only makes sense if QDoc is supposed to be used for more than 
just Qt itself.

BR,
~ Sput
-- 
Manuel "Sput" Nickschas         | mailto: manuel.nickschas at nokia.com |   .-.
Senior SW Engineer, Middlelayer | callto: +49 (0) 174 16 53 993      |   oo|
Nokia GmbH, MP Development      | sendto: Lise-Meitner-Str. 14       |  /`'\
Product Creation Center Ulm     |         89081 Ulm, Germany         | (\_;/)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120209/3e4b53fe/attachment.html>