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

[Sze Howe Koh]

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/20121023/5aed5d37/attachment.html>