[Development] Consistency in Qt headers (extends: 'renaming all QWindow properties that have "window" in them')

[Sze Howe Koh]

On Tue, Oct 30, 2012 at 7:45 PM, Sze Howe Koh <szehowe.koh at gmail.com> wrote:
> I'll begin cleaning up the selected Qt 5.0 modules first, then move on
> to the others later.

The renaming of QtMultimedia and QtMultimedia::MetaData has been
submitted for review:
    https://codereview.qt-project.org/38564
    https://codereview.qt-project.org/38573
    https://codereview.qt-project.org/38574
    https://codereview.qt-project.org/38575


Next up: QtConcurrent

Right now, the usage and documentation of the QtConcurrent namespace
is very different from the rest of Qt. Its functions are split between
3 different headers (function parameters omitted below):

    #include <QtConcurrentFilter>
        QtConcurrent::blockingFilter()
        QtConcurrent::blockingFiltered()
        QtConcurrent::blockingFilteredReduced()
        QtConcurrent::filter()
        QtConcurrent::filtered()
        QtConcurrent::filteredReduced()

    #include <QtConcurrentMap>
        QtConcurrent::blockingMap()
        QtConcurrent::blockingMapped()
        QtConcurrent::blockingMappedReduced()
        QtConcurrent::map()
        QtConcurrent::mapped()
        QtConcurrent::mappedReduced()

    #include <QtConcurrentRun>
        QtConcurrent::run()


Elsewhere in Qt, devs would #include the name of the namespace or
class (or even the overarching module) as the camel-case header, in
order to use its functions/enums:

    #include <QNamespace>
    ...
    int result = QNamespace::someFunc();


However, the QtConcurrent headerse don't follow this pattern --
QtConcurrent[Filter|Map|Run] do not correspond to any well-defined
part of Qt's class hierarchy.

Furthermore, each of the other namespaces have all their
functions/enums documented together under one page, but QtConcurrent
is split across 4 pages.

Thus, in combination with the other points mentioned in this thread, I propose:

    1) Deprecate the "QtConcurrent" namespace, in favour of "QConcurrent"
    2) Expose all Q(t)Concurrent functions under one camel-case header
("#include <QConcurrent>") for new code, while preserving the old
header files for compatibility
    3) Merge the (significantly overlapping) doc pages of the
Q(t)Concurrent functions [1-3] into the (currently very bare)
namespace page [4].

Is this ok? If so, I'll start making the changes.


Regards,
Sze-Howe

[1] http://doc-snapshot.qt-project.org/5.0/qtconcurrentfilter.html
[2] http://doc-snapshot.qt-project.org/5.0/qtconcurrentmap.html
[3] http://doc-snapshot.qt-project.org/5.0/qtconcurrentrun.html
[4] http://doc-snapshot.qt-project.org/5.0/qtconcurrent.html