[Development] Inconsistencies in namespace/module names, and associated problems in documentation

[Sze Howe Koh]

Hi all,

After encountering broken doc links in Qt 5.0, I noticed some
inconsistencies in the naming of Qt modules and namespaces. I asked about
them at the Qt-Project forums, and was advised to bring them to your
attention here.

The original post is at http://qt-project.org/forums/viewthread/20499/ but
here's a (hopefully) more structured version. It's broken down into 3 large
issues, along with examples and their consequences:


[1] Inconsistencies in naming conventions
- 2 out of 33 modules start with "Q" instead of "Qt"
- 3 (or 4) out of 14 namespaces start “Qt” instead of "Q"

Consequence of [1]:
* Users can’t simply deduce from a name if it’s referring to a module or
not. They need to remember exceptions to rules -- steeper learning curve.


[2] Inconsistencies in relating namespaces to modules
- The QtBluetooth module has the QBluetooth ("Q") namespace, but
- The QtLocation module has the QtLocation ("Qt") namespace, and
- The QtMultimedia module has the QtMultimedia ("Qt") namespace

Consequences of [2]:
* Users need to remember exceptions, as before
* The identical names trip up QDoc's automatic link-generator, which can't
tell if the link should point to the namespace page or the module page
* I presume that the name clashes led to [3]


[3] Moved module pages
- In Qt 4.8, the QtMultimedia module page is at
http://qt-project.org/doc/qt-4.8/qtmultimedia.html
- In Qt 5.0, the QtMultimedia module page MOVED to
http://qt-project.org/doc/qt-5.0/qtmultimedia-module.html
- In Qt 5.0, the QtMultimedia namespace page TOOK OVER
http://qt-project.org/doc/qt-5.0/qtmultimedia.html

Consequences of [3]:
* The "hierarchy bar" at the top of class refs (Qt Assistant, QtDevNet
docs) have broken or erroneous module links (
https://bugreports.qt-project.org/browse/QTWEBSITE-458)
* QtDevNet cross-version referencing is broken (
https://bugreports.qt-project.org/browse/QTWEBSITE-457)



I understand the need to maintain backwards-compatibility, but I think it's
also important to look for ways to keep Qt simple to learn, and
maintainable as it grows. What are your thoughts on how to address these
issues?


Regards,
Sze-Howe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120921/8f0bdce2/attachment.html>