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

[Sze Howe Koh]

Hi all,

The first proposed change has been submitted to Gerrit, to give QSql its
own camel-case header: https://codereview.qt-project.org/38294

Does anyone have any objections/suggestions for the rest of this plan? If
not, I'll start working on the next part: Renaming some namespaces that
were introduced in Qt 5 (QtLocation, QtMultimedia, QtMultimedia::Metadata)

I remain convinced that the current names are unsuitable. Take the Qt
Bluetooth module as the role model: "QtBluetooth" is its
compact-module-name and module-header-name for the whole module. There is a
"QtBluetooth" namespace, but that's internal (
https://qt.gitorious.org/qt/qtconnectivity/blobs/master/src/bluetooth/qbluetoothglobal.h)
-- the public namespace, and the public namespace-header, is "QBluetooth".
Taking Qt Location in contrast, "QtLocation" currently fills the role of
compact-module-name, module-header-name, AND public-namespace-name. This is
a name clash, and it also leaves no (consistent) way to #include the
namespace without pulling in the whole module.


Regards,
Sze-Howe

On Tue, Oct 23, 2012 at 12:16 AM, Sze Howe Koh <szehowe.koh at gmail.com>wrote:

> Hi all,
>
> Extending the discussion on good API naming schemes , I'd like to propose
> some tweaks for the API.
>
> To demonstrate the issues involved, here is a graphical overview of Qt's
> current quirks:
> https://docs.google.com/file/d/0B71n5SNZeRJybEd6ajhsQ1R4TVU/edit (compiled
> mainly from documentation, but also from studying Qt5beta1 headers)
>
>
> //==================
> // POTENTIAL BENEFITS
> //==================
>
> -- Help QDoc disambiguate (it can't tell the difference between, say,
> references to the QtMultimedia module, and references to the QtMultimedia
> namespace)
>
> -- Adherence to the no-nested-namespaces guideline (
> http://lists.qt-project.org/pipermail/development/2012-October/006759.html
> )
>
> -- Remove the need to #include an entire module, just to get a namespace
>
> -- Consistency for all #include's
>
> -- Matching module and namespace names -> Fewer names to remember
>
> -- Can intuitively tell that "#include <QtXyz>" would pull in the entire
> module, whilst "#include <QXyz>" would give me just the namespace
>
> -- Greater clarity in what a module/namespace contains
>
>
> //==================
> // PROPOSALS
> //==================
>
> Here are the proposals, from least disruptive to most disruptive (from a
> Qt user's POV, not necessarily from the repo's POV):
>
> -- Add meta-header <QSql>
>
> -- Rename module Qt Service Framework -> Qt Service; Rename meta-header
> <QtServiceFramework> -> <QtService>
>
> -- Rename namespace QtLocation -> QLocation; Add meta-header <QLocation>
>
> -- Rename namespace QtMultimedia -> QMultimedia; Rename header
> qtmedianamespace.h -> qmultimedia.h; Add meta-header <QMultimedia>
>
> -- Rename namespace QtMultimedia::MetaData -> QMediaMetaData; Add header
> qmediametadata.h; Add meta-header <QMediaMetaData>
>
> -- Rename namespace QtConcurrent -> QConcurrent; Add meta-header
> <QConcurrent>; Add namespace alias QtConcurrent = QConcurrent
>
> -- Rename namespace QGL -> QOpenGL; Add meta-header <QOpenGL>; Add
> namespace alias QGL = QOpenGL
>
> -- Rename module ActiveQt -> QtActiveX; Rename meta-header <ActiveQt> ->
> <QtActiveX>
>
> (-- Find a way to link the Qt Publish and Subscribe module with the
> QValueSpace namespace)
>
>
> //==================
> // EXTRA RATIONALES
> //==================
>
> -- The word "framework" is often implied in Qt modules: Qt Test is the
> test framework, Qt Location is the location framework, Qt QML is a UI
> framework... so Qt Service can be the service framework
>
> -- We don't have BlueQt, D-Qt, and WebQt; we have Qt Bluetooth, Qt D-Bus,
> and Qt WebKit. Also, "Qt ActiveX" is clearer than "ActiveQt"; same with
> QOpenGL vs QGL
>
> -- The QtPublishSubscribe module consists purely of QValueSpace* classes
> and the QValueSpace namespace, but their names don't show their
> relationship at all.
>
>
>
> I think "PublishSubscribe" is the more descriptive name, but QValueSpace*
> has been around for a long time in Qt Mobility. Can't think of a good
> solution for that one.
>
> I understand that these changes are rather large, so I'd like to hear the
> community's thoughts on the matter. Is it a good idea? A nice but
> impractical idea? A waste of time?
>
>
>
> Regards,
> Sze-Howe
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20121026/fe84aa56/attachment.html>