Misleading documentation of QHash/QMap?

JonB

I am troubled by the same sentence which the docs use for the behaviour of QHash/QMap. In the Detailed Description, second sentence, they both state:

It stores (key, value) pairs and provides fast lookup of the value associated with a key.

The more I read this the more I find it misleading. They do not supply "fast lookup of the value associated with a key". It is true that once the key has been located it's immediate to return the associated value, but that is also true of, say, a linear search of an array/vector: once you have spent time locating the right index/key the associated value is immediately available.

There is the method const Key QMap::key(const T &value, const Key &defaultKey = Key()) const which does indeed lookup a value in the map. And that correctly states:

Returns the first key with value value
This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

So looking up a value is slow, not fast, as I would expect.

Does anyone else think the wording in Detailed Description is unfortunately misleading? I would have documented by a sentence like:

It stores (key, value) pairs and provides fast lookup of a key.

Plain and simple, no mention of "value".

kkoehne

I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .

jsulm

@JonB Don't understand the problem to be honest :-) Usually you want to get the value associated with a specific key and that is fast when using QMap/QHash. But I'm not English native speaker :-)

JonB

@jsulm
Well there you are. I find the phrase

provides fast lookup of the value associated with a key.

very strange/misleading --- it implies the fast lookup is by value --- compared against the simpler

provides fast lookup of a key.

I had a look at, say, https://en.cppreference.com/w/cpp/container/map

std::map is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare. Search, removal, and insertion operations have logarithmic complexity.

No problem for me here, as the text does not try to say anything about fast lookup of the value associated with a key.

Maybe the Qt docs were not aimed at native English speakers :)

jsulm

@JonB said in Misleading documentation of QHash/QMap?:

Maybe the Qt docs were not aimed at native English speakers :)

It probably was written by a non-native speaker :-)

kkoehne

I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .

JonB

@kkoehne
Thanks, you're a gent :) Maybe it's just me! Marking yours as solution.

P.S.
Though how you're a Moderator with 120 posts, in 10 years, I'm not sure ;-)

kkoehne

Heh :) I got the Moderator's badge a while ago, when I was for some months the official TQtC contact person for the forum.

JKSH

@JonB To me, "look up a value" usually means "use this key/index to retrieve the value".

https://en.wikipedia.org/wiki/Associative_array says, "In computer science, an associative array, map, symbol table, or dictionary is an abstract data type composed of a collection of (key, value) pairs.... Operations associated with this data type allow... the lookup of a value associated with a particular key"
https://en.cppreference.com/w/cpp/container/map has a section labelled "Lookup" whose main operation is "finds element with specific key"

That's what I'm used to, so the current QHash/QMap documentation sounds right to me. Do you have any examples a different way of using "lookup"?

JonB

@JKSH
I seem to have said my piece.

"Fast lookup of/by key" is unambiguous.

"Fast lookup of the value associated with a key" is at least potentially ambiguous. It could be taken as "you can speedily look up the key from the value". I had to find the QMap::key() method to verify it did not work like that. If QMap did provide that as fast look up by value, I could easily document that with the phrase "Fast lookup of the value associated with a key".

@kkoehne has filed my suggestion. Where doubtless it will sit till Hell freezes over. So I'm content :)

kshegunov

@JonB said in Misleading documentation of QHash/QMap?:

@kkoehne has filed my suggestion. Where doubtless it will sit till Hell freezes over. So I'm content :)

Not for this minor stuff and not on gerrit. If he'd filed it in JIRA I'd have been long gone before it was ultimately closed by a bot.
... but I'm not giving it +1 ... I thrive on confusing and hard to understand things (and stuff, and things) ... ;)

fcarney

@JonB said in Misleading documentation of QHash/QMap?:

provides fast lookup of a key.

Sounds like looking up the key itself.

I am a native speaker and the phrase "It stores (key, value) pairs and provides fast lookup of the value associated with a key." seems unambiguous. Maybe it seems that way because my assumptions about what "key" and "value" mean in this context.

kshegunov

@fcarney said in Misleading documentation of QHash/QMap?:

I am a native speaker

Yes, as is he, so settle it out like real men! ;P