Somebody for special coding in documentation for deprecated classes?
In the meantime there seem to be a number of classes which are no longer first choice. Like the QFtp and QHttp. You find following recommendation:
"This class provides a direct interface to FTP that allows you to have more control over the requests. However, for new applications, it is recommended to use QNetworkAccessManager and QNetworkReply, as those classes possess a simpler, yet more powerful API."
Yes, it is right in the beginning of the detailed section, but most people will probably not see it, because after a while one is just looking for methods and what their parameters are.
Some color coding would be nice. A sidebar or may be the background colors are possibilities. This could help to prevent people to start getting something to work when there are better ways to do it.
BTW I do not want to claim the feather of someone else. "Here":http://developer.qt.nokia.com/forums/viewthread/7343/#43312 is the post where it was originally suggested.
I second the motion :)
I like __attribute__((deprecated)) and the likes for this sorta thing. This generates warnings in your build that the class or function is deprecated and will surely alert people of the fact that the class or function should preferably not be used.
Warnings when compiling are another possibility, but since I have obtained a lot of Qt related warnings after raising the warning level for compilation I am not sure. Anyhow it would be good to have every possibility used to make people aware.
A warning would be grate, but would also probably get lost in the massive warning dump that any Qt for Symbian application generates while compiling.
People should read details of class when using it. There is much information about subclassing etc. which should be read carefully.
Maybe all the details should be shown first and not only short summary?
Yes people should, but if you take a look at a big part of the questions posted here you'll find that a lot of people don't actually read the doc at all.
I think both the compiler warning (if that can be done in a cross-platform way) and a more prominent warning in the class would be good. On the docs here on devnet, depricated member functions are already clearly marked. Also, complete depricated classes like [[Doc:QHttp]] have a clear warning.
I think more "obtrusive" warnings, like compiler warnings or in-edtior warnings in QtCreator might help to prevent confusion on obsolete classes and methods. I would even go one step further and add the possibility to mark obsolete code as "error" (unavoidable) or "ignore" (as there is for sure plenty of obsolete code floating around).
In addition, there is still code which is not marked obsolete, but "already considered so":http://labs.qt.nokia.com/2011/05/12/qt-modules-maturity-level-the-list/. This fact should be reflected in the documentation.
However, the major problem in the first place is - as other have already stated - that people still do not read the documentation at all.
The documentation should be read carefully when starting to use classes. No doubt about that. Unfortunately, a lot of posts do not follow this rule. But that is as with the horse and the waterhole. You can bring the horse there, but you cannot make it drink. That is for one part.
However, if someone started to use a class in certain version, I do not believe that this person will read carefully all the details in the documentation when choosing an upgrade of Qt. Even then, it is easy to read over the note in the details section. For QFtp it could be a little more dominant in the current of documentation (e.g. marked with Note or Warning at the start of this paragraph). This would help already a lot. AFAIK is the documentation based on Doxygen this is providing already some means to do it. At least when using the standard style.
[quote author="Andre" date="1309594004"]I think both the compiler warning (if that can be done in a cross-platform way) and a more prominent warning in the class would be good. On the docs here on devnet, depricated member functions are already clearly marked. Also, complete depricated classes like [[Doc:QHttp]] have a clear warning.[/quote]
By checking Andre's link, I saw that QHttp is much better marked than QFtp, which I have used for starting this discussion. If QHttp is "clearly marked" as mentioned by Andre might be different understanding of "clearly marked". ;-)
An additional color coding in the back ground or as sidebar would alert people everywhere in the document.
The warnings will help people to see that there is a change when they have upgraded to a new version. It is certainly an option. However, I am not sure if it will be seen, especially when there are a lot of other warnings around anyhow.
If one is trying a use a class and looks at the documentation, it is quite obvious. I also understand that Qt documentation provides a list of "obsolete classes":http://doc.qt.nokia.com/4.7/obsoleteclasses.html each version. But unless you're constantly looking to keep the code up-to-date, you might not keep track of it. I usually compile the new version.. fire up assistant and continue working on the client's requirements. Maybe, it would be good to make that page more prominent and have a more in-your-face-visibility web page for it here on devnet. But then again, i don't see too many classes on the list. Anyhoo...