Somebody for special coding in documentation for deprecated classes?

kkrzewniak · wrote on 1 Jul 2011, 17:29

I second the motion :)

Franzk · wrote on 1 Jul 2011, 17:40

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.

koahnig · wrote on 1 Jul 2011, 17:57

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.

kkrzewniak · wrote on 1 Jul 2011, 18:01

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.

tomma · wrote on 1 Jul 2011, 20:32

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?

kkrzewniak · wrote on 2 Jul 2011, 07:28

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.

andre · wrote on 2 Jul 2011, 08:06

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.

lgeyer · wrote on 2 Jul 2011, 08:51

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.

koahnig · wrote on 2 Jul 2011, 09:33

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.

jim_kaiser · wrote on 2 Jul 2011, 09:34

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...