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 :) 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. 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. All of the above is my personal opinion of course, and *NOT* representative of the Qt Documentation team, qdoc team or any other team in Nokia. I like Doxygen, and have used it on several occasions for my own personal projects; but I still feel that the output of qdoc looks better. (And no, I *don't* use the inheritance charts. I think they are pointless, and not nice to look at. If you need them, something is obviously too complex in your design.) -- .marius _______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development