Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-114663

QtConcurrent docs only refer to header which pulls in QtCore module header

    XMLWordPrintable

Details

    Description

      The documentation for methods in the QtConcurrent Namespace only refers to the module header include,

      #include <QtConcurrent>
      

      See https://doc.qt.io/qt-6/qtconcurrent.html & https://doc.qt.io/qt-5/qtconcurrent.html.

      That module header though comes with the price tag of including all the module's headers as well as the QtCore module header, which again includes all of the QtCore headers.

      For developers who want to follow the include-only-what-you-use, this is not optimal. Even more when using QtConcurrent code in public headers of an own library, spoiling all the library consumers.
      While peeking into the set of installed headers, one can see individual headers together with CamelCase forwarding headers like qtconcurrentrun.h & QtConcurrentRun.
      But those are not mentioned in the documentation, so there is a chance these might not be official.

      Wanted:
      for developers who use methods of the QtConcurrent namespace, like QtConcurrent::run(...), the documentation would specify headers like QtConcurrentRun. So developers can rely on that API documentation "contract" and use them without fearing they will disappear during the Qt6 (or any more Qt5) cycle. And do not have to opt into the heavy-price-tag module header instead, given only that is documented.

      And while adding that, ideally the examples would be also updated to use the includes recommended here (preferred: the CamelCase ones). Right now they are a mix, using documented and undocumented includes:

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/runfunction/main.cpp?h=5.15

      #include <qtconcurrentrun.h>
      

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/map/main.cpp?h=5.15

      #include <qtconcurrentmap.h>
      

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/progressdialog/main.cpp?h=5.15

      #include <QtConcurrent>
      

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/imagescaling/imagescaling.h?h=6.5

      #include <QtConcurrent>
      

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/primecounter/primecounter.h?h=6.5

      #include <QtConcurrent/qtconcurrentfilter.h>
      #include <QtConcurrent/qtconcurrentreducekernel.h>
      

      https://code.qt.io/cgit/qt/qtbase.git/tree/examples/qtconcurrent/wordcount/main.cpp?h=6.5:

      #include <QtConcurrent/qtconcurrentmap.h>
      

      Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            docteam Qt Documentation Team
            kossebau Friedrich W. H. Kossebau
            Votes:
            1 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:

              Gerrit Reviews

                There are no open Gerrit changes