Somebody for special coding in documentation for deprecated classes?
-
I second the motion :)
-
-
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.
-
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...