Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Get Qt Extensions
  • Unsolved
Collapse
Brand Logo
  1. Home
  2. General talk
  3. Brainstorm
  4. Somebody for special coding in documentation for deprecated classes?
QtWS25 Last Chance

Somebody for special coding in documentation for deprecated classes?

Scheduled Pinned Locked Moved Brainstorm
11 Posts 7 Posters 4.1k Views
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • K Offline
    K Offline
    koahnig
    wrote on 1 Jul 2011, 17:15 last edited by
    #1

    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.

    Vote the answer(s) that helped you to solve your issue(s)

    1 Reply Last reply
    0
    • K Offline
      K Offline
      kkrzewniak
      wrote on 1 Jul 2011, 17:29 last edited by
      #2

      I second the motion :)

      Me, Grimlock, not "nice dino". ME BASH BRAINS!

      1 Reply Last reply
      0
      • F Offline
        F Offline
        Franzk
        wrote on 1 Jul 2011, 17:40 last edited by
        #3

        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.

        "Horse sense is the thing a horse has which keeps it from betting on people." -- W.C. Fields

        http://www.catb.org/~esr/faqs/smart-questions.html

        1 Reply Last reply
        0
        • K Offline
          K Offline
          koahnig
          wrote on 1 Jul 2011, 17:57 last edited by
          #4

          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.

          Vote the answer(s) that helped you to solve your issue(s)

          1 Reply Last reply
          0
          • K Offline
            K Offline
            kkrzewniak
            wrote on 1 Jul 2011, 18:01 last edited by
            #5

            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.

            Me, Grimlock, not "nice dino". ME BASH BRAINS!

            1 Reply Last reply
            0
            • T Offline
              T Offline
              tomma
              wrote on 1 Jul 2011, 20:32 last edited by
              #6

              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?

              1 Reply Last reply
              0
              • K Offline
                K Offline
                kkrzewniak
                wrote on 2 Jul 2011, 07:28 last edited by
                #7

                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.

                Me, Grimlock, not "nice dino". ME BASH BRAINS!

                1 Reply Last reply
                0
                • A Offline
                  A Offline
                  andre
                  wrote on 2 Jul 2011, 08:06 last edited by
                  #8

                  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.

                  1 Reply Last reply
                  0
                  • L Offline
                    L Offline
                    lgeyer
                    wrote on 2 Jul 2011, 08:51 last edited by
                    #9

                    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.

                    1 Reply Last reply
                    0
                    • K Offline
                      K Offline
                      koahnig
                      wrote on 2 Jul 2011, 09:33 last edited by
                      #10

                      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.

                      Vote the answer(s) that helped you to solve your issue(s)

                      1 Reply Last reply
                      0
                      • J Offline
                        J Offline
                        jim_kaiser
                        wrote on 2 Jul 2011, 09:34 last edited by
                        #11

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

                        1 Reply Last reply
                        0

                        1/11

                        1 Jul 2011, 17:15

                        • Login

                        • Login or register to search.
                        1 out of 11
                        • First post
                          1/11
                          Last post
                        0
                        • Categories
                        • Recent
                        • Tags
                        • Popular
                        • Users
                        • Groups
                        • Search
                        • Get Qt Extensions
                        • Unsolved