Re: [Development] RFC: The Future of QDoc
On Monday, February 13, 2012 09:04:22 casper.vandonde...@nokia.com wrote: Whatever is chosen (updating qdoc, or changing to Doxygen): The task is not small, and therefore it would be nice if there would be more contributors than just me and Martin Smith. Maybe it would be a good idea to have a sit-down at the Contributors Summit (if people are interested). Have you actually been in contact with Dmitri about merging the features and effort into doxygen? I looked at the mailing list and saw nothing. It would be a good start, and a good idea to bring him to the summit to if that turns out to be a good or welcome idea. Thanks, -- Stephen Kelly stephen.ke...@kdab.com | Software Engineer KDAB (Deutschland) GmbH Co.KG, a KDAB Group Company www.kdab.com || Germany +49-30-521325470 || Sweden (HQ) +46-563-540090 KDAB - Qt Experts - Platform-Independent Software Solutions signature.asc Description: This is a digitally signed message part. ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 11/02/2012, at 12:47 AM, André Somers wrote: 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 +1 This is basically what we do with our code. When documentation is in the headers, developers are less likely to update them because they know that it will trigger potentially large rebuilds. If the docs are in the .cpp file, then they will update pretty much any trivial thing because it's only going to cause that one file to be rebuilt (okay, plus maybe some subsequent relinking). I'm also a big fan of the put the documentation close to the code philosophy. That tends to encourage keeping the documentation up to date. -- Dr Craig Scott Computational Software Engineering Team Leader, CSIRO (CMIS) Melbourne, Australia ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 10/02/2012, at 5:13 AM, marius.storm-ol...@nokia.commailto:marius.storm-ol...@nokia.com marius.storm-ol...@nokia.commailto:marius.storm-ol...@nokia.com wrote: 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. As someone who has submitted a number of bug reports to the Doxygen project, Dmitri has been pretty good at responding to issues. As you'd expect, the better the quality of your issue description, the better the response. Providing a means to reproduce a problem typically gets a very good response. Support for other languages has been added over time to Doxygen. I see little reason why something similar couldn't be done for QML. Sure, someone other than Dmitri would probably have to do it, but that's going to be true for qdoc anyway, isn't it? My understanding is that there are some other fairly major contributors to doxygen, but perhaps those people only get a mention in the release emails. 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). A counter-argument here is that for those projects that use Doxygen rather than qdoc for their own documentation, it means that you can't incorporate Qt's documentation into your own. This is precisely the case for us, for example. We provide a large Qt-based framework with Doxygen-generated help content. We can't provide links to docs for the Qt classes, etc. because it uses qdoc. We like the Doxygen output and it works well for us, and I suspect there are a lot more projects out there using Doxygen than qdoc. So while qdoc might result in better Qt documentation on its own, does the choice of using qdoc more commonly result in poorer documentation for projects that use Qt? 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. It might be possible to alleviate some of the workload using doxygen aliases to simulate missing qdoc commands. -- Dr Craig Scott Computational Software Engineering Team Leader, CSIRO (CMIS) Melbourne, Australia ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On Friday 10 February 2012 08:07:07 Andre Somers wrote: Op 9-2-2012 19:13, marius.storm-ol...@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) ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/9/12 10:44 PM, ext BRM bm_witn...@yahoo.com wrote: From: casper.vandonde...@nokia.com casper.vandonde...@nokia.com 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. Why would Doxygen need QML itself? Or do you mean it would need to be able to process the QML/JavaScript files to get additional documentation? I mean that Doxygen needs to support parsing .qml files and .cpp files containing QML files (and that it should generate the same look of content for both of them). 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 can understand bundling a version of Doxygen with Qt in the release - like many projects do for their dependencies in case those things are not on the platform people are building on. E.g. Subversion bundles libneon. However, I see no issue with saying that Doxygen version x.y.z is required to support documentation. So why would we need to _fork_ it as opposed to simply bundling a version that is known to work? Doxygen does not support everything we need. Maybe at some point we (the Qt project) will not require any new features from the documentation tool, then we can obviously just ship a Doxygen version that is known to work. What I mean is that in the beginning we'll probably have a situation similar to Gerrit, where we have a version deployed with the Qt project that is mainline with some extra patches applied (which is a fork in my book, or at least temporarily, until the patches are integrated in mainline). That would not occur when Doxygen releases are lined up with Qt (or when we get lucky and Doxygen releases a version before a Qt release which has all our patches applied). Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/10/12 8:07 AM, ext Andre Somers an...@familiesomers.nl wrote: Op 9-2-2012 19:13, marius.storm-ol...@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? 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) Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
Op 2/10/2012 2:15 PM, casper.vandonde...@nokia.com schreef: On 2/10/12 8:07 AM, ext Andre Somersan...@familiesomers.nl wrote: Op 9-2-2012 19:13, marius.storm-ol...@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é ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
From: casper.vandonde...@nokia.com casper.vandonde...@nokia.com On 2/9/12 10:44 PM, ext BRM bm_witn...@yahoo.com wrote: From: casper.vandonde...@nokia.com casper.vandonde...@nokia.com 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. Why would Doxygen need QML itself? Or do you mean it would need to be able to process the QML/JavaScript files to get additional documentation? I mean that Doxygen needs to support parsing .qml files and .cpp files containing QML files (and that it should generate the same look of content for both of them). Ok. That makes sense. 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 can understand bundling a version of Doxygen with Qt in the release - like many projects do for their dependencies in case those things are not on the platform people are building on. E.g. Subversion bundles libneon. However, I see no issue with saying that Doxygen version x.y.z is required to support documentation. So why would we need to _fork_ it as opposed to simply bundling a version that is known to work? Doxygen does not support everything we need. Maybe at some point we (the Qt project) will not require any new features from the documentation tool, then we can obviously just ship a Doxygen version that is known to work. What I mean is that in the beginning we'll probably have a situation similar to Gerrit, where we have a version deployed with the Qt project that is mainline with some extra patches applied (which is a fork in my book, or at least temporarily, until the patches are integrated in mainline). Again, this makes sense. I wouldn't necessarily say it's a fork - no more so than a distribution packaging something with additional patches is a fork; but it's just a matter of how the Qt community works with the Doxygen community to get the support required then. That would not occur when Doxygen releases are lined up with Qt (or when we get lucky and Doxygen releases a version before a Qt release which has all our patches applied). A matter of timing and working with the Doxygen community. I know - it probably won't happen for a while; but we probably should have someone reach out to Doxygen devs to get their input on what can be done, and what we would need to add. $0.02 Ben ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 10/02/2012 07:46, ext Oswald Buddenhagen wrote: On Fri, Feb 10, 2012 at 01:15:19PM +, ext casper.vandonde...@nokia.com wrote: does adding the documentation to the headers not make compilation slower? pretty much negligible. but: putting docs into headers causes many unnecessary recompiles due to the headers being included into many .cpp files. Now *that's* a fair and important point, IMO. -- .marius ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
[Development] RFC: The Future of QDoc
Hello, 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? Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? Keno ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 2/9/12 3:15 PM, ext Keno Fischer ke...@stanford.edu wrote: Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? I think that QDoc will indeed use the parser from Creator (whatever that will be, the last answer from Andre Poenitz was to use a hybrid), unless someone comes up with other great ideas. The problem stays that QDoc is not fully modularized (QDoc will depend on Creator/an independent module containing the parser). But maybe that is something we cannot circumvent (unless we let QtBase depend on Clang and have our own parser, but that will not work on every platform I assume). Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 9 February 2012 14:15, Keno Fischer ke...@stanford.edu wrote: Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? There's also the KDevelop C++ parser. It already supports many C++11 features and run very fast. As far as I'm aware it doesn't depends on any KDE libraries (Qt only) and already has the ability to extract Doxygen-style comments. I don't know if there are any KDevelop people on this list who can comment further? -- Matt Williams http://milliams.com ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
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...) 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 :) BR, ~ Sput -- Manuel Sput Nickschas | mailto: manuel.nicksc...@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 | (\_;/)___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 09/02/2012 10:16, ext Hugo Parente Lima wrote: On Thursday 09 February 2012 14:30:20 Matt Williams wrote: On 9 February 2012 14:15, Keno Fischerke...@stanford.edu wrote: Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? There's also the KDevelop C++ parser. It already supports many C++11 features and run very fast. As far as I'm aware it doesn't depends on any KDE libraries (Qt only) and already has the ability to extract Doxygen-style comments. I don't know if there are any KDevelop people on this list who can comment further? The KDevelop parser is based on a version of Roberto's parser, last time I checked the sources it used few KDE utility classes like some smart pointers, but I see no difference in using the KDevelop or QtCreator parser as both are more or less the same. QtCreators parser is a much later version of Roberto's parser, and I expect that it parses much faster than the KDevelop one. I'm sure QtCreators parser can be upgraded to also handle those new C++11 features, and since we need to maintain it in Creator anyways, I don't see why it should use another parser than a one we already have intimate knowledge about? I nice ability QDoc would have is to support other output formats like XML or JSON, the old QDoc had this feature but it was deprecated and not documented at all. The PySide documentation is generated using the XML output of qdoc3, but the current version of qdoc3 doesn't support XML output anymore. Oops. Casper, Martin any details about this, and why XML output was dropped? Hugo, any reason why PySide cannot use the normal output? Integration with other help tools? -- .marius ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On Thursday 09 February 2012 17:56:12 marius.storm-ol...@nokia.com wrote: On 09/02/2012 10:16, ext Hugo Parente Lima wrote: On Thursday 09 February 2012 14:30:20 Matt Williams wrote: On 9 February 2012 14:15, Keno Fischerke...@stanford.edu wrote: Implement a new C++ parser Any plans on using Clang a parser? The wiki page mentioned Qt Creator's AST, but it seems like Qt Creator will be moving away from its own implementation in the future, so I think that might be something to consider. Also, since the necessary work on Clang is being done for Qt Creator anyway (I'm thinking of things like signals/slots) it might be worth to keep qdoc in mind when working on Clang for Qt Creator. Any thoughts? There's also the KDevelop C++ parser. It already supports many C++11 features and run very fast. As far as I'm aware it doesn't depends on any KDE libraries (Qt only) and already has the ability to extract Doxygen-style comments. I don't know if there are any KDevelop people on this list who can comment further? The KDevelop parser is based on a version of Roberto's parser, last time I checked the sources it used few KDE utility classes like some smart pointers, but I see no difference in using the KDevelop or QtCreator parser as both are more or less the same. QtCreators parser is a much later version of Roberto's parser, and I expect that it parses much faster than the KDevelop one. I'm sure QtCreators parser can be upgraded to also handle those new C++11 features, and since we need to maintain it in Creator anyways, I don't see why it should use another parser than a one we already have intimate knowledge about? I nice ability QDoc would have is to support other output formats like XML or JSON, the old QDoc had this feature but it was deprecated and not documented at all. The PySide documentation is generated using the XML output of qdoc3, but the current version of qdoc3 doesn't support XML output anymore. Oops. Casper, Martin any details about this, and why XML output was dropped? Hugo, any reason why PySide cannot use the normal output? Integration with other help tools? XML output was dropped because it wasn't maintained and was never made public, it always was a private experimental thing from qdoc3. We couldn't use the normal output because we need to modify the Qt documentation without touch the Qt sources, so the qdoc3 outputs XML files generated from Qt sources, we apply some XSLT's to change small things, then we transform those XML's into rst files and send them to sphinx to create the docs formatted in a python friendly way. -- Hugo Parente Lima signature.asc Description: This is a digitally signed message part. ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
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
Re: [Development] RFC: The Future of QDoc
Hi, I nice ability QDoc would have is to support other output formats like XML or JSON, the old QDoc had this feature but it was deprecated and not documented at all. The PySide documentation is generated using the XML output of qdoc3, but the current version of qdoc3 doesn't support XML output anymore. Oops. Casper, Martin any details about this, and why XML output was dropped? Hugo, any reason why PySide cannot use the normal output? Integration with other help tools? XML output was dropped because it wasn't maintained and was never made public, it always was a private experimental thing from qdoc3. We couldn't use the normal output because we need to modify the Qt documentation without touch the Qt sources, so the qdoc3 outputs XML files generated from Qt sources, we apply some XSLT's to change small things, then we transform those XML's into rst files and send them to sphinx to create the docs formatted in a python friendly way. Have you looked at the DITA XML output we generate now? It is pretty stable now, we tried to use it for the 4.8 DevNet release, but the output was not fully up to spec at that point. It is now. You can find more information about DITA XML at http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html The version of DITA Open Toolkit we are using to apply XSLTs can be found at https://projects.developer.nokia.com/doxygen_dita/files Casper ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
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 ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
On 09/02/2012 12:13, ext marius.storm-ol...@nokia.com wrote: On 09/02/2012 10:33, ext Manuel Nickschas wrote: 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. Btw, all purely based on http://doxygen.svn.sourceforge.net/viewvc/doxygen/trunk/ and committers I can see in the revision logs. I have not been in contact with Dimitri on the matter, but I do see a call to action in http://old.nabble.com/Doxygen-support-for-QML---td32658060.html. So perhaps a wrong assumption on my part. -- .marius ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
From: casper.vandonde...@nokia.com casper.vandonde...@nokia.com 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. Why would Doxygen need QML itself? Or do you mean it would need to be able to process the QML/JavaScript files to get additional documentation? 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 can understand bundling a version of Doxygen with Qt in the release - like many projects do for their dependencies in case those things are not on the platform people are building on. E.g. Subversion bundles libneon. However, I see no issue with saying that Doxygen version x.y.z is required to support documentation. So why would we need to _fork_ it as opposed to simply bundling a version that is known to work? Just curious, Ben ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
Op 9-2-2012 19:13, marius.storm-ol...@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é ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] RFC: The Future of QDoc
Op 10-2-2012 8:07, Andre Somers schreef: Op 9-2-2012 19:13, marius.storm-ol...@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(). Oh, and that is not mentioning templates either... André ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
