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
_______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
