So, we have the Qt 5 beta out! The next steps now are to polish it to make the Qt 5.0.0 release as impressive as possible.
One big, pending task we've identified is making sure the class reference documentation is consistent with the changes we've made in Qt 5. Since this was originally written when widgets were the only way to do GUIs in Qt, some of the documentation is rather widget-centric in how it presents things. There might also be other content in there that is no longer correct, or less relevant, with the changes made in Qt 5.
The only way to fix this is really to go through the classes manually. We need to actually read the documentation for each class to make sure it still makes sense and presents Qt in a way that give people the information they need to make good decisions. If it is somehow unclear or seems stuck in the past, we need to update it with something better.
One example of such an update was in the QSyntaxHighlighter docs, where the description of the class referred to a constructor which had been removed in Qt 5, when the class was made independent of widgets. This reference was simply removed. Another example was the QTextDocument docs, which have been rephrased a little to identify the class as a general rich text layout engine, and not only as the back-end for QTextEdit, which is just one isolated use case in the context of Qt 5. Note, though, that for the majority of classes, there will not be any issues, but we won't know for sure until someone's read the documentation and verified it.
If you've been looking to get into developing on the Qt Project, this might be good time to get started. It's definitely a very useful way to get familiar with the different parts of Qt and the infrastructure around it, and the patches you'll be making are simple and low risk.
To organize the work, we've made a wiki-page. If you want to help out, please edit the page and replace "unassigned" with your name next to the class you're claiming to avoid duplicate work. If the class requires patching, please make sure the change is actually merged before you mark the class as "done".
To get started with Qt development, go to the Qt Project homepage and look at the guides posted there. You might also have use for the QDoc reference documentation to figure out what all the magic tags are for.
Finally, just ask if you have any questions. We really appreciate any help we can get with this!
Commenting for this post has ended.
With Firefox in GNU/Linux the wiki page is slow to load and fails when laoding jquery. Good luck!
Indeed, as Colin says, http://qt-project.org/wiki/... is horribly slow to load and freezes Chrome for ~20 seconds. The minified 1-liner .js scripts are hard to profile in Web Inspector, so no clue where exactly the bottleneck is.
Why do we need such heavy JavaScript in the Wiki?
"We need to actually read the documentation for each class to make sure it still makes sense and presents Qt in a way that give people the information they need to make good decisions.
I don't quite get the point you're trying to make. Because it is obvious that the class documentation should be up to date and reflect the current state of the api(s). And we, the developers using Qt, have always been blessed with good documentation, thank you.
I think that the documentation should serve the developers to to their job, whether it be widgets or qml the choice of the taste. An important entry point is the "Qt Reference Documentation" page and as to what it is today, it pretty much serves Qt developers well (and yes, Qt Tool Manuals - entry is important too ;) ):
http://doc-snapshot.qt-proj...
aportale: I don't know what the bottle neck is either. We tried some changes on the assumption that it was trying to make links out of all the Qt class names because they look like wiki page names, but we haven't been able to improve it any further than this (it was even worse when there was a table in there).
It seems to completely break FireFox, it's tolerable in Chrome (as you say it hangs for a few seconds but then it resumes), and there's no noticeable effect in Opera. If this turns out to be a big issue, we'll have to divide the class list into smaller pieces, I think, unless there's a way to disable the JavaScript it's running for this page.
JubiLuM: The point is that most the documentation was written a long time ago, so some of it is now out of date. For instance, the documentation to QAbstractItemModel mentions QListView and QTableView, but it does not mention the QML elements that can also be used with it. There's no way to grep for these things, so we actually need human sanity checks for each class to make sure it represents the reality in Qt 5 and not Qt 4.
Eskil:
Thank you for clarifying. I understand the lag in the documentation as Qt has been evolving with speed and has gained totally new aspects on its way. I wish the community (developers using qt, qt community developers) can also help in the process to make the documentation even better. Least we can do is give feedback...which I have been doing more than the doctor ordered (well, I've filled some bugreports also, so not just plain nagging) :).
Well, shouldn't documentation be generated from the Qt sources? Thus changes, made in Qt5 should automatically update - removed features will have their documentation removed, new and modified features will have they documentation added or updated.
7: The documentation for a removed feature will automatically be removed, yes, so this refers to references to usage in the documentation of features that are not removed. E.g. the description of QSyntaxHighlighter said something to the effect of "use the constructor that takes a QTextEdit". However, that constructor had been removed when widgets were made a separate module. There's no way the documentation generator can detect those cases.
Just FYI, the doc snapshot still links to the QtQuick1 version of the Qt Quick module docs instead of the QtQuick2 version of the QtQuick module docs. See for example the links on the QML development landing page: http://doc-snapshot.qt-proj... in the "What Is Qt Quick" section - they point to http://doc-snapshot.qt-proj... instead of http://doc-snapshot.qt-proj... as they should. At the very least, please replace those automatic links with manually specified l{http://doc-snapshot.qt-proj...}{Qt Quick} links.
I did mention the issue to Casper on IRC but it looks like it hasn't been fixed yet.
I would like to help with documentation and development.
If you are interested, please contact me. Thanks.
Would it be possible to incorporate a "last updated" field within the docs? This could be useful in the long term as Qt continues to evolve
I'd like to jump in and help out. Some questions:
1. Do we submit doc patches to Gerrit, just like source code patches?
2. How does this effort integrate with the Documentation reports at https://bugreports.qt-proje... ? I've submitted some "bug reports" about Qt docs before. Those have been assigned to people in the issue tracker; can I just take over and fix them myself?
Hello,
Qt 5 can be so cute for developement company as one that i'm working on it. But must of developer don't have any information about new technology and good improvement and power of Qt. Some of them has works on Qt in very early years ago (days of Trolltech).
Leaders of my company prefer C#/.Net and Java for developement. They like to see some enterprise projects that works on new technologies of Qt like QtQuick.
I think QtQuick can remove WPF/.Net easily, but more simplicity and productivity is required. Documentation is week and samples could not presents power of Qt/QtQuick.
I suggest you to firing up a competition just some weeks after firing Qt5 final version for developing on QtQuick/Qt5 for best logic, best idea, fastest developement, most platform indepentent developement, best performance, best documentation and so on. Remote developement could be a good news for developers around the world.
And i like to say you, Nokia is imported into a political game over Iran. They prevent us from accessing to download links (QtSDK). This approach harms Qt project.
Goodluck - Mousavi
Please don't make suggestions or bug reports in the comment field here. Use https://bugreports.qt-proje... otherwise they are likely to be forgotten.
Chris Adams: Yes, we're looking at that and several other high level documentation problems. Thanks :)
JKSH: Submit doc patches just like code patches, yes. And you're of course very welcome to take over documentation bugs in the bug tracker and fix them yourself. :) Just make sure that they're not marked as "In Progress" so we avoid doing duplicate work.
All right, I've updated http://qt-project.org/wiki/... with sub-pages, so it should be more manageable for FireFox and friends now.