PDO docs and spec problem

Hello

I do think the comments for the various PDO functions can be helpful to 
specific the needs or the workarounds people need to use.
There is a general lack of documentation how flags interact, what flags 
belongs to what kind of query, this makes users (including me) not very 
happy.
Guess work how a function or flag works should be avoided, no surprises 
please!

Looking at the source:

#define PDO_FETCH_FLAGS 0xFFFF0000 /* fetchAll() modes or'd to 
PDO_FETCH_XYZ */
#define PDO_FETCH_GROUP 0x00010000 /* fetch into groups */
#define PDO_FETCH_UNIQUE 0x00030000 /* fetch into groups assuming first 
col is unique */
#define PDO_FETCH_SERIALIZE 0x00080000 /* fetch class instances by 
calling serialize */
#define PDO_FETCH_PROPS_LATE 0x00100000 /* fetch props after calling ctor */

Now that’s not very helpfully either, as example I don’t think 
FETCH_PROPS_LATE belong to the fetchAll case.

About PDO_FETCH_UNIQUE I am unsure, at least my tests today showed that 
pdo mysql show a new behaviour, it works without PDO_FETCH_GROUP and 
results in something like MDB2/DB getAssoc. I am quite sure my last 
tests with php < 5.3 assumed GROUP in the past. Now I would really like 
to use that feature, but how stable is it when the user documentation 
and code assumes PDO_FETCH_GROUP should be used?!?

(It doesn’t mention it kills the first column in the result set, I would 
like to have it for creating an ORM object; And now I already ask for a 
feature improvement, sorry)

Is PDO_FETCH_KEY_PAIR even documented somewhere? The comment in the 
header file doesn’t mention that you really need to have only two columns.

I think this description of PDO::FETCH_SERIALIZE is technical wrong.:
Docs say: “As PDO::FETCH_INTO but object is provided as a serialized 
string. Available since PHP 5.1.0.”
The PDO code seems to agree with me that it really belongs to FETCH_CLASS.

Before new features and bug fixing can be done, I think the 
documentation of PDO needs love. If you use the PDO docs as specs how 
PDO should work then new bugs will be introduced.

A new wiki page would be a useful starting point to cleanly describe the 
behaviour of various flags and how they work (together)?

Best regards
Oskar Eisemuth