Qt 5.0 namespace/module naming inconsistencies are ugly, and are wreaking havoc on online documentation...

JKSH

I'm very curious: How were module names and namespaces chosen?

It seems that most modules have the "Qt" prefix, and most namespaces have the "Q" prefix. However, there are exceptions:

2 out of 33 "modules":http://qt-project.org/doc/qt-5.0/modules.html use the "Q" prefix
3 out of 14 "namespaces":http://qt-project.org/doc/qt-5.0/namespaces.html use the "Qt" prefix

Also, there are inconsistencies in relating namespaces to their corresponding modules, e.g.:

For Bluetooth, the module is called QtBluetooth, while the namespace is called QBluetooth ("Q"). Same goes to DBus, SQL, and Test
For Multimedia, the module is called QtMultimedia, and the namespace is ALSO called QtMultimedia ("Qt"). Same goes to QtLocation.

These inconsistencies are ugly and somewhat disorienting; I can't simply deduce from a name if it's referring to a module or not. Worse still, they're wreaking havoc on the Docs. For example, http://qt-project.org/doc/qt-5.0/qtlocation.html says

bq. The QtLocation namespace contains miscellaneous identifiers used throughout the QtLocation module.

The bolded bits are automatically-generated hyperlinks. From the text, it's obvious that one should point to the namespace page and the other should point to the module page. However, QDoc can't tell them apart, and both links lead to the same page.

That's not all; QtDN integration has broken too, thanks to the chosen naming scheme for namespaces, modules, and HTML pages. Previously, the QtMultimedia module is at http://qt-project.org/doc/qt-4.8/qtmultimedia.html . However, it has since been moved to http://qt-project.org/doc/qt-5.0/qtmultimedia-module.html presumably to give the old address to the new namespace. This has caused the "Select version" drop-down menu on QtDN to break; switching versions in a module page gives a 404 error.

And then, there's the the 'hierarchy bar':

!http://i.imgur.com/ojndP.png(QtDN class ref screenshot)!

The circled link should point to the class's parent module (which is does, for Qt 4.8). However, for Qt 5.0, you either get taken to the namespace page (for QtMultimedia and QtLocation classes) or get a 404 error (for all other classes).

I think we have a consistency and maintainability problem. How should we solve this?

Change the namespace/module names? Which ones? (assuming this is even thinkable, from a backwards compatibility point of view)
** Some inconsistencies have existed since Qt 4
** The QtMultimedia and QtLocation namespaces were introduced in Qt 5; it may be possible to rename these without breaking things (too badly?)
Change the HTML page naming system?
Update QDoc?
Update the QtDN website code? How?
** Add logic to handle different versions? (...but will this become a maintenance nightmare if Qt5 -> Qt6 introduces more doc structure changes?)
** Remove ability to switch between major versions?)
Combination of the above?
Ignore this?

sierdzio

This belongs more to testing subforum than to the Lounge. I suggest you post some of your findings (especially those listed at the beginning) to Qt development mailing list. Documentation is being heavily worked upon at the moment, I think your input can help. To me it seems that inconsistencies you've found are mostly leftovers from incorporating mobility into Qt5.

JKSH

Ah, ok. I've reported the post to ask a mod to move this.

I've previously filed bug reports about broken links at "QTWEBSITE-457":https://bugreports.qt-project.org/browse/QTWEBSITE-457 & "QTWEBSITE-458":https://bugreports.qt-project.org/browse/QTWEBSITE-458 ; should I contact the mailing list too?

[EDIT] I guess the issue is about a lot more than broken links. Writing to the mailing list now.

sierdzio

Thanks, I've seen the post there :)

JKSH

It doesn't seem to be attracting any interest. I haven't interacted with a dev community via a mailing list before; should I have presented my observations differently? Was I too blunt, or unclear in purpose, perhaps?

sierdzio

I don't know why noone has picked it up, really. I thought it to be very important thing to fix, wesp. before the final release.

andre

Perhaps you can ping caspar directly. Try on IRC (freenode network) in the #qt-labs channel, and look for user cvandonderen

JKSH

Thanks for the lead, Andre; will try to contact Caspar.

JKSH

By the way, what is Caspar's role? Should we gather others as well? I think this is a multi-component issue, involving:

Qt's very structure
Documentation
The DevNet

andre

Caspar is documentation -manager- maintainer.