[Development] Proposal: Deprecate QVector in Qt 6
berglerma at gmail.com
Thu Apr 23 21:36:56 CEST 2020
Am Do., 23. Apr. 2020 um 21:01 Uhr schrieb Giuseppe D'Angelo via
Development <development at qt-project.org>:
> On 4/23/20 6:54 PM, Manuel Bergler wrote:
> >> This is a documentation bug or a Creator bug. You're supposed to land on
> >> this anchor:https://doc.qt.io/qt-5/qvariant.html#QVariantList-typedef
> > Technically this is the correct place to land on, but it isn't
> > helpful. Just like Julius, if I have a container most of the time I
> > care about the API of the container, not about the API of the
> > value_type. So I expect to see the API for that container when I open
> > the documentation, but when intuitively scrolling up to the list of
> > member functions it sometimes takes several seconds for me to realize
> > that I landed on the QVariant page instead. If it were written as
> > QList<QVariant> I could choose to either open the documentation for
> > QVariant or for QList.
> This is still a suggestion for Qt Creator, though. Note that the link
> above contains links to both QList and QVariant.
I am aware of that. But by the time I realize I have the documentation
for the wrong type I'm no longer at that place. The way I tend to use
the documentation is for exploration of the API, so the very first
thing I always do is to scroll to the list of member functions. I
don't even bother reading where I initially ended up in the
documentation. So as soon as I open the documentation for QVariantList
I scroll to the top until I reach the member function list. And then I
notice that some of these don't seem right, and I realize I'm looking
at the documentation for QVariant even though I need the one for
QList. But at that point it is too late. And it happens every time,
because that way to use the documentation is so habitual simply
because it works in 99% of the cases.
> >>> And I have to remember if QStringList is the same as as QList<QString>,
> >>> or if it's actually a different container with a different API.
> >> In fact, it is-a QList<QString>. What's the problem here with its naming?
> > The issue is that Qt itself is not consistent with the naming.
> > QStringList is just an alias for QList<QString>, but e.g. QDomNodeList
> > (https://doc.qt.io/qt-5/qdomnodelist.html) isn't. So unless you've
> > frequently used the particular type you always have to look it up. If
> > it were spelled as QList<QString> it'd be obvious.
> This is:
> 1) an indication that by using "List" in the type name we don't actually
> mean QList, but we mean "sequence of"; and/or
> 2) an API mistake.
I agree it is an API mistake, but that doesn't change the situation
that the existence of that API makes it so that I cannot be sure
whether something that ends in "List" is a typedef or its own type and
I have to look it up every time. If the aliases were deprecated and
the full type were used instead, then in the majority of cases I don't
have to look it up because it is spelled out and I know the API of
QList. Only in the few remaining cases where a type ending in "List"
I'd have to look it up to check whether this is one of the old aliases
or a separate type. Another case that comes to mind that I have to
look up every time: QVariantMap. I always forget what the key type is
because I use it so infrequently.
> Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
> KDAB (France) S.A.S., a KDAB Group company
> Tel. France +33 (0)4 90 84 08 53, http://www.kdab.com
> KDAB - The Qt, C++ and OpenGL Experts
> Development mailing list
> Development at qt-project.org
More information about the Development